General

As from version 1.4.0 Sealights python agent supports AWS lambda functions.

Support Model

Pre Requisites

AWS lambda functions are small and short pieces of code that is invoked by calling to an http endpoint.

In order to support coverage monitoring by Sealights agent here are the pre-requisties:

Sealights Python Agent version 1.4.0 and above
Sealights Collector version 0.18.0 and above
Additional step on the pipeline sequence to configure the lambda support
Changes to AWS deployment manifest ( See below for full end-end example)

How Sealights Lambda Support Works

The support of AWS lambda functions is handled by a lambda internal layer (sealights_layer) that is installed during the pipeline steps (more on that step is below) and intercepting the original lambda handler.
Here is the flow when the lambda function is invoked:

Step 1 - Execution of setup code

Within the sealights_layer code, there's a setup file that runs during the initialization of the lambda function.

The setup file operates as follows:

#!/usr/bin/env python3
# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: MIT-0

import os

args = os.sys.argv[1:]

orig_name = os.environ.get('_HANDLER', '')  # Getting the original handler name
os.environ['_HANDLER'] = 'wrapper.lambda_handler'  # Setting the wrapper as the handler
os.environ['ORIG_NAME'] = orig_name  # Setting the original handler name as an environment variable

os.system(" ".join(args))  # Calling the original handler - Start the runtime

This code intercepts the original lambda handler name and replaces it with the Sealights lambda handler.

Step 2 - Invoking the Sealights Lambda Handler

Once the setup and initialization are complete, the AWS backend calls the Sealights lambda handler, which then loads and begins processing the request.

Step 3 - Loading `sl_lambda_config.json`

As part of the configuration process, a configuration file essential for processing the footprints is saved to the root of the original lambda directory. This file is later loaded for use. If, for any reason, this configuration file is not found, fails to load, or is invalid, a message will be printed to the log. However, the lambda will continue to execute normally without interruptions.

Step 4 - Initiating Coverage

After loading the configuration, the code initiates coverage monitoring and saves all coverage data to a temporary file.

Step 5 - Invoking the Original Lambda Function

Once coverage monitoring has started, the code invokes and retrieves the original lambda's response.

Step 6 - Terminating Coverage

After the original lambda function has completed and provided a response, coverage monitoring is halted. The data is then processed into a Footprint data JSON, making it ready for transmission to the collector.

Step 7 - Transmitting Footprints to the Collector

At this juncture, a brief HTTP POST request is made to the collector, sending the footprint model.

Step 8 - Returning the Response

Following the communication with the collector, the original lambda handler's response is relayed back to the AWS backend.

Configuration

There are two steps needed to be done in order to add support of Sealights agent to existing lambda code.

Use the new sl-python command ‘configlambda’ after the scan and before the deployment.
Change deployment manifest to includes the support of Sealights lambda layer

Running sl-python configlambda command

The sl-python configlambda has 3 additional flags to the general flags such as as token and bsid.

Flag	Description	Type	Mandatory	Example
`--slconfigpaths`	Set the location of all lambda functions root dir	List of paths	Yes, at least one path is required	“./function_1,./function_2"
`--collectorurl`	Set the address of the collector URL	a valid URL	No, but if not set by ENV Var the footprints will not be set	https://collector.host:16500
`--exportlayerpath`	Set the path of saving the sealights_layer	a valid dir	No, but if not set a sealights_layer will be saved	"./"

sl_lambda_config.json

This json file contains the agent config parameter's that needed to be sent in each footprint.

This file MUST be present at the root of the lambda folder in order to be loaded when the Sealights lambda handler is invoked

Deployment Manifest Changes

There are two main changes that need to be done to the deployment manifest:

Adding Sealights Lambda layer - contains the code of the sealights lambda support
Add reference to Sealights Lambda Layer on every Lambda function definition.

Example:

....
Resources:
### Adding Sealights Lambda Layer
  SealightsLayer:
    Type: AWS::Serverless::LayerVersion
    Properties:
      LayerName: sealights_layer
      Description: Layer for managing code coverage
      ContentUri: sealights_layer/
      CompatibleRuntimes:
        - python3.11
### End of Sealights Lambda Layer        
  Function1:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri:  function_1/
      Handler: app.lambda_handler
      Runtime: python3.11
### Start of Ref to Sealights Layer Support
      Layers:
          - !Ref SealightsLayer
      Environment:
        Variables:
          AWS_LAMBDA_EXEC_WRAPPER: /opt/setup
### End of Ref to Sealights Layer Support           
      Events:
        HelloWorld:
          Type: Api
          Properties:
            Path: /function1
            Method: get
.....

Important Notes:

The Content Uri in Sealights Layer should be to related --exportlayerpath path on sl-python configlambda command
The 'AWS_LAMBDA_EXEC_WRAPPER: /opt/setup' is a mandatory env var to set in order to invoke Sealights Lambda handler

Additional Optional Environment Variables:

In addition to the mandatory 'AWS_LAMBDA_EXEC_WRAPPER: /opt/setup' environment variable there are more environment variables that override the sl_lambda_config.json values:

Environment Variable Name	Description	Type
SL_DEBUG	Set Sealights lambda debug mode	Boolean
`SL_APP_NAME`	Set app name	string
`SL_BUILD_NAME`	Set build name	string
`SL_BRANCH_NAME`	Set branch name	string
`SL_BUILD_SESSION_ID`	Set build session id name	string
`SL_COLLECTOR_URL`	Set collector url	URL
`SL_LAB_ID`	Set Lab Id	string

Code Example

Code repository

https://github.com/liornabat-sealights/lambda-python-example

This code repository contains two lambda functions. function1 and function2

Setup

Here are the steps to add sealights lambda support.

Step 0 - Config and scanning

Before we adding the Sealights support, we need to install the sl-python agent, create bsid with config and perform a scan (as any python code)

Step 1 - Running sl-python configlambda

Run:

sl-python configlambda --slconfigpaths "./function_1,./function_2" --collectorurl "https://all-peas-press.loca.lt" --exportlayerpath "./"

Where the collector URL should set to the real collector url

Step 2 - Amending the deploy manifest

Here is the original deploy manifest

AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Description: sealigths-lambda-example-prod
Globals:
  Function:
    Timeout: 30

Resources:
  Function1:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri:  function_1/
      Handler: app.lambda_handler
      Runtime: python3.11
      Events:
        HelloWorld:
          Type: Api
          Properties:
            Path: /function1
            Method: get
  Function2:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri:  function_2/
      Handler: app.lambda_handler
      Runtime: python3.11
      Events:
        HelloWorld:
          Type: Api
          Properties:
            Path: /function2
            Method: get
Outputs:
  Function1:
    Description: "Sealights Lambda Function1 ARN"
    Value: !Sub "https://${ServerlessRestApi}.execute-api.${AWS::Region}.amazonaws.com/Prod/function1/"
  Function2:
    Description: "Sealights Lambda Function2 ARN"
    Value: !Sub "https://${ServerlessRestApi}.execute-api.${AWS::Region}.amazonaws.com/Prod/function2/"

We will add Sealights Layer and do changes to the functions settings.

Here is the amended deployment manifest:

AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Description: sealigths-lambda-example-sl
Globals:
  Function:
    Timeout: 30

Resources:
  SealightsLayer:
    Type: AWS::Serverless::LayerVersion
    Properties:
      LayerName: sealights_layer
      Description: Layer for managing code coverage
      ContentUri: sealights_layer/
      CompatibleRuntimes:
        - python3.11
  Function1:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri:  function_1/
      Handler: app.lambda_handler
      Runtime: python3.11
      Layers:
          - !Ref SealightsLayer
      Environment:
        Variables:
          AWS_LAMBDA_EXEC_WRAPPER: /opt/setup
          SL_DEBUG: true
      Events:
        HelloWorld:
          Type: Api
          Properties:
            Path: /function1
            Method: get
  Function2:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri:  function_2/
      Handler: app.lambda_handler
      Runtime: python3.11
      Layers:
          - !Ref SealightsLayer
      Environment:
        Variables:
          AWS_LAMBDA_EXEC_WRAPPER: /opt/setup
      Events:
        HelloWorld:
          Type: Api
          Properties:
            Path: /function2
            Method: get
Outputs:
  Function1:
    Description: "Sealights Lambda Function1 ARN"
    Value: !Sub "https://${ServerlessRestApi}.execute-api.${AWS::Region}.amazonaws.com/Prod/function1/"
  Function2:
    Description: "Sealights Lambda Function2 ARN"
    Value: !Sub "https://${ServerlessRestApi}.execute-api.${AWS::Region}.amazonaws.com/Prod/function2/"

Using Python Agent - AWS Lambda Support