Leveraging the codesec.yaml file
The .lacework/codesec.yaml file is a source file you can add in your repository. The file defines the repository's scan profile and can contain custom configuration for both IaC and SCA binary components. The file is optional and only required if the customer wishes to apply repository specific configuration at scan time.
This topic highlights the following capabilities of the codesec.yaml file:
-
Enable/disable the scanning tool framework, including
terraform,cloudformation,helm, andkukbernetes. See Minimum requirements. -
Review available options for IaC and SCA. See Available options.
-
Control pull/merge request options. See Pull requests.
-
Enable/disable the
opal,checkov, ortfsecscanning tools. See Scanning tools. -
Define exceptions for individual findings, policies, or file paths. See Exceptions.
-
Define custom exit conditions which control the exit code of an IaC scan. See Exit conditions.
The .lacework folder must be in the root directory of the repository.
The codesec.yaml file has a higher level of precedence than the settings in the Settings > Code security > Settings page.
SCA license compliance can also be configured in the codesec.yaml file. See Configuring the license compliance policy.
Minimum requirements
The minimum requirements for .lacework/codesec.yaml is to either enable or disable scanning. It is enabled by default (enabled: true).
To enable the file:
default:
iac:
enabled: true
sca:
enabled: true
To disable the file:
default:
iac:
enabled: false
sca:
enabled: false
Available options
The following tables reference available options for both IaC and SCA binary components.
IaC
|
Command |
Description |
|---|---|
|
lacework iac config generate |
Generate your local scan profile configurations file at |
|
lacework iac config show |
Show the full scan profile configurations. This is to be used during a scan invocation, such as |
|
lacework iac config show-default |
Show out-of-the-box default full scan profile configurations. See |
|
lacework iac config show-diff |
Show the differences between your runtime scan profile configurations and the |
|
lacework iac config show-remote |
Show the current remote FortiCNAPP platform scan profile configurations. This includes |
|
lacework iac config validate |
Validate your local |
The following demonstrates using the lacework iac config show command:
~/misbehaving-org/insecure-kubernetes-deployments (git)-(main) -> lacework iac config show
* ScanProfile configuration:
default:
iac:
enabled: true
pullRequest:
auditMode: false
commentOnlyHighAndCritical: false
comments: true
scan:
autofix: false
checkov: true
checkovModuleDownload: false
cloudformation: true
dockerfile: true
exceptions:
- path:test/*:Accepted risk
- CWE:CWE-89:Accepted risk
- policy:lacework-iac-aws-security-3:Accepted risk
exitConditions:
any:
- attribute: severity
operator: '>'
threshold: 0
value: critical
- attribute: severity
operator: '>'
threshold: 0
value: high
enabled: true
helm: true
kubernetes: true
kustomize: true
opal: true
terraform: true
terraformPlan: true
tfsec: true
sca:
enabled: true
pullRequest:
auditMode: true
commentOnlyHighAndCritical: false
comments: true
scan:
acf: false
acfLocations: 5
acfLocationsFull: []
exceptions:
- path:insecure-js/package-lock.json:Accepted risk
- path:test/*:Accepted risk
- fingerprint:3DBC93CF72BA03B2:False positive
- path:test/*:Accepted risk
- fingerprint:EB84ACEDB25E4DED:Compensating controls
- path:insecure-js/server.js:Accepted risk
gitHistory: false
licenseDetection: true
linesOfCode: true
sast: true
scr: true
secret: true
vulnEvaluation: true
For more information on the configuration parameters and options for IaC, run the lacework iac scan -help command.
SCA
|
Command |
Description |
|---|---|
|
lacework sca config generate |
Generate your local scan profile configurations file at |
|
lacework sca config show |
Show the full scan profile configurations. This is to be used during a scan invocation, such as |
|
lacework sca config show-default |
Show out-of-the-box default full scan profile configurations. See |
|
lacework sca config show-diff |
Show the differences between your runtime scan profile configurations and the |
|
lacework sca config show-remote |
Show the current remote FortiCNAPP platform scan profile configurations. This includes |
|
lacework sca config validate |
Validate your local |
For more information on the configuration parameters and options for SCA, SAST, and Secrets, run the lacework sca scan -help command.
Pull requests
Pull requests (PR) can be configured as follows:
default:
iac:
pullRequest:
auditMode: false|true # OPTIONAL FIELD, default: false
commentOnlyHighAndCritical: false|true # OPTIONAL FIELD, default: false
comments: false|true # OPTIONAL FIELD, default: false
sca:
pullRequest:
auditMode: false|true # OPTIONAL FIELD, default: false
commentOnlyHighAndCritical: false|true # OPTIONAL FIELD, default: false
comments: false|true # OPTIONAL FIELD, default: false
Scanning tools
The scanning tools opal, checkov, and tfsec can be enabled or disabled in the scan section by setting the value to true or false. IaC can also be configured to download third party checkov modules during a scan.
Default values are shown in the following example:
default:
iac:
enabled: true
scan:
opal: true
tfsec: true
checkov: true
checkovModuleDownload: false
Scanning frameworks can also be enabled or disabled by setting the value to true or false. The following example shows all available frameworks and their default values:
default:
iac:
enabled: true
scan:
terraform: true
terraformPlan: true
cloudformation: true
helm: true
kubernetes: true
kustomize: true
dockerfile: true
Exceptions
Code security exceptions reduce the number of reported vulnerabilities detected. Exceptions can be configured for whole files or individual instances. Once an exception has been configured, the vulnerabilities identified by the instance or file path will not be included in the next scan.
For more information on exceptions, see Exception management.
Exceptions can be defined based on the policy, path, or fingerprint. When defining a new exception, you must add an entry to the list of exceptions, along side a reason and description.
The exception method is dependent on the scan:
|
Exception method |
Scanning support |
|||
|---|---|---|---|---|
|
IaC |
SCA |
SAST |
Secrets |
|
|
Policy |
Yes |
No |
No |
No |
|
Path |
Yes |
Yes |
Yes |
Yes |
|
Fingerprint |
Yes |
Yes |
Yes |
Yes |
In order to add an exception for a finding from our scanners you need to modify the .lacework/codesec.yaml file, or create it if it does not exist. Exceptions can be defined as an array of strings with a criteria, value and reason separated by colons: <criteria>:<value>:<reason>.
The following values are accepted when configuring exceptions in the codesec.yaml file:
|
Field |
Accepted value |
|---|---|
|
Criteria |
|
|
Reason |
|
Considerations:
-
The reason is optional and will be defaulted to
Accepted risk. -
Criteria and reason values are case-sensitive.
The following is an example of configuring an exception:
default:
iac:
enabled: true
scan:
exceptions:
- policy:lacework-iac-aws-security-3:Accepted risk
- policy:lacework-iac-aws-storage-1:Accepted risk
- policy:lacework-iac-aws-security-4:Accepted risk
sca:
enabled: true
scan:
exceptions:
- "path:tests/fixtures/*:Accepted risk"
Exit conditions
Exit codes only apply to IaC scanning. SCA scanning is not currently supported.
Exit conditions allows the evaluation of an exit code based on scan results and configuration of policy severity thresholds in a scan profile. The number of violations of each severity found during the scan will be evaluated against thresholds in the scan profile. You can define whether the scan should exit with 0 or with an exit code determined by the evaluation. In any case where no violations or errors occur, it will exit with 0.
The default configuration is as follows:
default:
iac:
enabled: true
scan:
exitConditions:
enabled: true
any:
- attribute: severity
value: critical
operator: '>'
threshold: 0
- attribute: severity
value: high
operator: '>'
threshold: 0
Exit codes can be enabled (enabled: true) or disabled (enabled: false):
-
Enabled: This is the default value. It will exit with a non-zero code is any critical or high vulnerabilities are found.
-
Scan completed with no violations and no errors:
exit 0 -
Scan complete with no violations and some errors:
exit 190 -
Scan completed with violations above the configured exit condition and no errors:
exit 160 -
Scan completed with violations above the configured exit condition and some errors:
exit 161 -
Scan had failed run, other critical error and typically no results:
exit 1
-
-
Disabled: It will exit with a non-zero code if any violations of any severity are found.
-
Scan completed with no violations and no errors:
exit 0 -
Scan complete with no violations and some errors:
exit 190 -
Scan completed with violations and no errors:
exit 150 -
Scan completed with violations and some errors:
exit 151 -
Scan had failed run, other critical error and typically no results:
exit 1
-
Examples
Additional examples of custom exit conditions are as follows:
-
A single exit condition: Evaluate only if critical violations are found
default: iac: enabled: true scan: exitConditions: enabled: true attribute: severity value: critical operator: '>' threshold: 0 -
All conditions: Evaluate if both critical and high violations are found
default: iac: enabled: true scan: exitConditions: enabled: true all: - attribute: severity value: critical operator: '>' threshold: 0 - attribute: severity value: high operator: '>' threshold: 0 -
Compound condition: Evaluates for any critical, any high, or if more than 10 medium violations and 20 low violations are found.
default: iac: enabled: true scan: exitConditions: enabled: true all: - attribute: severity value: critical operator: '>' threshold: 0 - attribute: severity value: high operator: '>' threshold: 0 - all: - attribute: severity value: medium operator: '>' threshold: 10 - attribute: severity value: low operator: '>' threshold: 20