This project has been publicly archived. Please visit github.com/openclarity or openclarity.io to discover our other projects!
FunctionClarity is a code integrity solution for serverless functions. It allows users to sign their serverless functions and verify their integrity prior to their execution in their cloud environments. FunctionClarity includes a CLI tool, complemented by a "verification" function deployed in the target cloud account. The solution is designed for CI/CD insertion, where the serverless function code/images can be signed and uploaded before the function is created in the cloud repository.
This version supports serverless functions on AWS (Lambda functions) only, support for Azure functions and Google functions/cloud-run are part of the near-term roadmap plan.
- Deploy FunctionClarity – deploy FunctionClarity "validation" function in the target cloud account (a one time operation); this function will scan and verify new functions when created or updated in the target account
- Sign functions - use FunctionClarity CLI to sign the function code or image in the user’s environment, and then upload it to the target cloud account
- Deploy the serverless function - using the signed function code/image
- Verify functions - the FunctionClarity verifier function is triggered when user functions are created or updated in case they meet the filter criteria, and does the following:
- Fetches the function code from the cloud account
- Verifies the signature of the function code image or zip file
- Follows one of these actions, based on the verification results:
- Detect - marks the function with the verification results
- Block - tags the function as 'blocked', if the signature is not correctly verified, otherwise does nothing
- Notify - sends a notification of the verification results to an SNS queue
If a function is tagged as blocked, it will be prevented from being run by AWS when it is invoked.
Go to the function clarity latest release:
- Create a folder and download:
aws_function.tar.gzand extract it to the folderfunctionclarity-v<version_number>for your OS type and extract it to the folder
This section explains how to get started using FunctionClarity. These steps are involved:
- Initialize and deploy FunctionClarity
- Sign and upload serverless function code
- Sign and verify new AWS functions
- Verify functions:
- From the cloud account
- From the FunctionClarity command line
Follow these steps from a command line, to install FunctionClarity in your AWS account.
Run the command from the folder in which the FunctionClarity tar file is located.
As part of the deployment, a verifier function will be deployed in your cloud account, which will be triggered when lambda functions are created or updated in the account. This function verifies function identities and signatures, according to the FunctionClarity settings.
A configuration file will also be created locally, in ~/.fc, with default values that are used when signing or verifying functions, unless specific settings are set with command line flags.
- Run the command
./functionclarity init aws - When prompted, enter the following details:
enter Access Key: ********
enter Secret Key: ********
enter region: <your_region_name>
enter default bucket (you can leave empty and a bucket with name functionclarity will be created):
enter tag keys of functions to include in the verification (leave empty to include all):
enter the function regions to include in the verification, i.e: us-east-1,us-west-1 (leave empty to include all):
select post verification action : (1) for detect; (2) for block; leave empty for no post verification action to perform
enter SNS arn if you would like to be notified when signature verification fails, otherwise press enter:
is there existing trail in CloudTrail (in the region selected above) which you would like to use? (if no, please press enter):
do you want to work in keyless mode (y/n): n
enter path to custom public key for code signing? (if you want us to generate key pair, please press enter):
Enter password for private key:
Enter password for private key again:
Private key written to cosign.key
Public key written to cosign.pub
Uploading function-clarity function code to s3 bucket, this may take a few minutes
function-clarity function code upload successfully
deployment request sent to provider
waiting for deployment to complete
deployment finished successfully
Use the command below to sign a folder containing function code, and then upload it to the user cloud account.
./functionclarity sign aws code /sample-code-verified-folder
using config file: /Users/john/.fc
Enter password for private key:
Code uploaded successfullyUse AWS cli to deploy a signed lambda function to your cloud account, or to update lambda code in the account
If the verifier function is deployed in your account, and in case it meets the filter criteria then any function create or update event will trigger it to verify the new or updated function. It will follow the post-verification action (detect, block, or notify).
If the action is 'detect', the function will be tagged with the FunctionClarity message that the function is verified:
If the action is block, the function's concurrency will be set to 0 and the function will be throttled:
You can also use the CLI to manually verify a function. In this case, the function is downloaded from the cloud account, and then verified locally.
./functionclarity verify aws funcclarity-test-signed --function-region=us-east-2
using config file: /Users/john/.fc
Verified OKFunctionClarity includes several advanced commands and features, which are described below.
FunctionClarity leverages cosign to sign and verify, code, for both key-pair and keyless signing techniques.
./functionclarity init aws| Argument | Description |
|---|---|
| access key | AWS access key |
| secret key | AWS secret key |
| region | AWS region in which to deploy FunctionClarity |
| default bucket | AWS bucket in which to deploy code signatures and FunctionClarity verifier lambda code for the deployment |
| post verification action | action to perform after verification (detect, block; leave empty for no action to be performed) |
| sns arn | an SNS queue for notifications if verification fails, leave empty to skip notifications |
| CloudTrail | AWS cloudtrail to use; if empty a new trail will be created |
| keyless mode (y/n) | work in keyless mode |
| public key for code signing | path to public key to use when verifying functions; if blank a new key-pair will be created |
| privte key for code signing | private key path; used only if a public key path is also supplied |
| function tag keys to include | tag keys of functions to include in the verification; if empty all functions will be included |
| function regions to include | function regions to include in the verification, i.e: us-east-1,us-west-1; if empty functions from all regions will be included |
| Flag | Description |
|---|---|
| only-create-config | determine whether to only create config file without actually deploying |
The import-key-pair command provide the ability to import your existing PEM-encoded, RSA or EC private key, use this command:
./function-clarity import-key-pair --key key.pemThe deploy command does the same as init, but it uses the config file, so you don't
need to supply parameters using the command line
./functionclarity deploy awsFunctionClarity supports signing code from local folders and images. When signing images, you must be logged in to the docker repository where your images deployed.
NOTE:
If a default config file exists (in ~/.fc) it will be used. If a custom config file flag is included in the command line, it will be used instead of the default file. If flags are included in the command line, they will be used and take precedence.
To sign code, use this command:
./functionclarity sign aws code <file/folder to sign> --flags (optional if you have configuration file)To sign images, use this command:
./functionclarity sign aws image <image url> --flags (optional if you have configuration file)These are optional flags for the sign command:
| flag | Description |
|---|---|
| access key | AWS access key |
| secret key | AWS secret key |
| region | AWS region in which to deploy signature (relevant only for code signing) |
| bucket | AWS bucket in which to deploy code signature (relevant only for code signing) |
| privatekey | key to use to sign code |
NOTE:
If a default config file exists (in ~/.fc) it will be used. If a custom config file flag is included in the command line, it will be used instead of the default file. If flags are included in the command line, they will be used and take precedence.
Command for verification
./functionclarity verify aws <function name to verify> --function-region=<function region location> --flags (optional if you have configuration file)These are optional flags for the verify command:
| flag | Description |
|---|---|
| access key | AWS access key |
| secret key | AWS secret key |
| region | AWS region from which to load the signature from (relevant only for code signing) |
| bucket | AWS bucket from which to load signatures from (relevant only for code signing) |
| key | public key for verification |
The update-func-config command is usefull when you want to update configuration related to the verifier lambda. The command updates the runtime configuration of the verifier lambda function in the aws environment.
NOTE:
If a default config file exists (in ~/.fc) it will be used. If a custom config file flag is included in the command line, it will be used instead of the default file. If flags are included in the command line, they will be used and take precedence.
Command for updating verifier configuration
./function-clarity update-func-config aws --flags (optional if you have configuration file)These are optional flags for the update-func-config command:
| flag | Description |
|---|---|
| access key | AWS access key |
| secret key | AWS secret key |
| region | AWS region where the verifier lambda runs |
| action | action to perform after verification (detect, block; leave empty for no action to be performed) |
| includedfunctagkeys | tag keys of functions to include in the verification; if empty all functions will be included |
| includedfuncregions | function regions to include in the verification, i.e: us-east-1,us-west-1; if empty functions from all regions will be included |
| snsTopicArn | an SNS queue for notifications if verification fails, leave empty to skip notifications |