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.gz and extract it to the folder
  • functionclarity-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.

1. Run the command ./functionclarity init aws
2. 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 successfully

Use 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 OK

FunctionClarity 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

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.pem

The 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 aws

FunctionClarity 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:

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:

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: