functionclarity

README

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.

How does it work?

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

Download FunctionClarity

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

Quick start

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

Initialize and deploy FunctionClarity

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

Sign function code

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

Deploy a function or update function code

Use AWS cli to deploy a signed lambda function to your cloud account, or to update lambda code in the account

Verify function code

Verify automatically on function create or update events

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:

Verify manually

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

Advanced use

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.

Init command detailed use

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

Import your own signing key

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

Deploy command detailed use

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

Sign command detailed use

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.

---

Examples

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

Verify command detailed use

---

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

Update verifier function configuration command detailed use

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