Using Python Agent - AWS Lambda Support
- Jason Wides
- Samantha Gray
- Medhat Sammar
.
- 1 General
- 1.1 Support Model
- 1.2 Pre Requisites
- 1.3 How Sealights Lambda Support Works
- 1.3.1 Step 1 - Execution of setup code
- 1.3.2 Step 2 - Invoking the Sealights Lambda Handler
- 1.3.3 Step 3 - Loading sl_lambda_config.json
- 1.3.4 Step 4 - Initiating Coverage
- 1.3.5 Step 5 - Invoking the Original Lambda Function
- 1.3.6 Step 6 - Terminating Coverage
- 1.3.7 Step 7 - Transmitting Footprints to the Collector
- 1.3.8 Step 8 - Returning the Response
- 2 Configuration
- 3 Code Example
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.
Test Duration Requirement
Please note that tests must run for a minimum of 1s for SeaLights to calculate coverage. If your test duration is under 1s, adding a brief pause to your test will allow SeaLights to complete the coverage sampling process.
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 |
|---|---|---|---|---|
| Set the location of all lambda functions root dir | List of paths | Yes, at least one path is required | “./function_1,./function_2" |
| 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 |
| Set the path of saving the sealights_layer | a valid dir | No, but if not set a sealights_layer will be saved | "./" |
Alternatively to exporting the layer, you can use the public layers in aws:arn:aws:lambda:eu-west-1:442677231940:layer:sl-python-layer:10arn:aws:lambda:eu-west-2:442677231940:layer:sl-python-layer:10arn:aws:lambda:us-east-1:442677231940:layer:sl-python-layer:10arn:aws:lambda:us-west-2:442677231940:layer:sl-python-layer:10
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/sealights-extension
### 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
--exportlayerpathpath on sl-python configlambda commandThe '
AWS_LAMBDA_EXEC_WRAPPER: /opt/sealights-extension' 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/sealights-extension' 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 |
| Set app name | string |
| Set build name | string |
| Set branch name | string |
| Set build session id name | string |
| Set collector url | URL |
| Set Lab Id | string |
Code Example
Code repository
GitHub - 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.
after running this command a file called sl_lambda_config.json will be created.
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/sealights-extension
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/sealights-extension
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/"