Create a Custom Policy

This article will show you how to create a custom policy for use with NG SAST.

You must have administrative privileges to create or modify policies.

NG SAST Policy Templates

NG SAST offers two default policy templates that you can use as the foundation when creating new custom policies:

  • default: creates a policy that imports all standard definitions used by ShiftLeft and the generic dictionary of sensitive data variables
  • no-dictionary: creates a policy that excludes the use of ShiftLeft's generic dictionary of sensitive data variables; ShiftLeft only uses the standard definitions to identify vulnerabilities

We recommend using one of the default policy templates to create a custom policy instead of creating one from scratch.

Creating a Custom Policy

To create and use a custom policy, you will need to:

  1. Create the new policy file
  2. Write the policy definition
  3. Validate your policy
  4. Upload the policy to the ShiftLeft repository
  5. Assign the policy to an application

Step 1: Create a New Policy File

Run the following to create a new policy file:

sl policy create [default|no-dictionary] <filepath>
ParameterDescription
`[defaultno-dictionary]`
<filepath>The location where you want NG SAST to create your new policy; policy files use the .policy extension

Step 2: Write the Policy Definition

Open your newly created policy file using a text editor. You can either:

  • Write new policy definitions
  • Edit the imported policy definitions (if you created the file using the default policy as your template)

Step 3: Validate the New Policy

After you write new policy definitions or editing the existing definitions, you must validate your new policy to make sure that there are no errors. To do so, run:

sl policy validate <filepath_to_policy>
ParameterDescription
<filepath>The file path to your policy

This command returns a non-zero exit status code if there is a problem with either the syntax or the semantics of your policy.

If there are no issues with your policy, you'll see a message similar to the following:

policy `test-policy.policy` is valid

Otherwise, you'll receive a notification similar to the following with error-related information:

Error: policy verification failed: invalid policies:
Policy format error:
pos: 6:19
message: mismatched input 'ssn' expecting {'VAR', 'VAR_REGEX'}
[ERROR] policy verification failed: invalid policies:
Policy format error:
pos: 6:19
message: mismatched input 'ssn' expecting {'VAR', 'VAR_REGEX'}
| issuer=/go/src/github.com/ShiftLeftSecurity/go-services/cmd/sl/main.go:1259

Step 4: Upload the Policy to the ShiftLeft Repository

NG SAST can only use a policy if it is located in the ShiftLeft repository. To upload a custom policy, run:

sl policy push <policyLabel>:<policyTag> <filepath>
ParameterDescription
<policyLabel>The name of your new policy. You may use underscores, but you may not use hyphens (e.g., test-policy isn't valid, but test_policy is valid)
<policyTag>Optional. The policy version (e.g., if your policy is myPolicy:0.0.1, then your policy version is 0.0.1)
<filepath>The file path to your policy

If you successfully upload your policy, ShiftLeft returns to the CLI your Org ID policy and tag:

uploaded policy: d64...2399/test_policy:latest

You can check for this policy in the repository by using the info command. The info command lists all policies uploaded with the specified label that is available to you.

Please note that you must provide the complete policy name (e.g., <OrgId>/<policyLabel>:<policyTag> )

sl policy info <policyLabel>:<policyTag>
ParameterDescription
<policyLabel>The name of the policy you want found; if omitted, ShiftLeft returns all available policies
<policyTag>Optional. The policy version (e.g., if your policy is myPolicy:0.0.1, then your policy version is 0.0.1); if omitted, the response includes all authorized policies

You can expect a response similar to the following:

Found policies:
[1] Policy:
Name: d64...99/test_policy
Tag: latest
Created at: 2020-06-02T11:43:30-05:00
Updated at: 2020-06-02T11:43:30-05:00
Hash: a0200f87452439017b6d1403d90919923ae739d048ac38b95fa490557f19ba4c

Since you can overwrite policy filenames, you may get multiple policy entries returned for a single table/tag.

Step 5: Assign the New Policy

When running NG SAST to analyze your application, you'll need to assign the policy for use with the app:

sl analyze --policy <policyLabel> --app <name>
ParameterDescription
<policyLabel>The name of the policy you want to be used for code analysis; if omitted, ShiftLeft uses its baseline policy
<policyTag>Optional. The policy version (e.g., if your policy is myPolicy:0.0.1, then your policy version is 0.0.1); if omitted, the response includes all authorized policies
nameThe name of your application

A sample command might look like the following:

sl analyze --policy d64f...399/test_policy:latest

How to Turn a Custom Policy into a Default Policy

If you find yourself using a custom policy frequently, you can turn it into a default policy that NG SAST automatically uses whenever it analyzes code:

sl policy assignment set <policyLabel>
ParameterDescription
<policyLabel>The name of the policy you want found; if omitted, ShiftLeft returns all available policies

Alternatively, you can also set a custom policy as the default policy for a specific application or application version (instead of globally for use with all applications):

sl policy assignment set --project <name> <policyLabel>:<policyTag>
ParameterDescription
<policyLabel>The name of the policy you want found; if omitted, ShiftLeft returns all available policies
<policyTag>Optional. The policy version (e.g., if your policy is myPolicy:0.0.1, then your policy version is 0.0.1); if omitted, the response includes all authorized policies
nameThe name of your application

When using a custom policy, NG SAST tends to identify fewer vulnerabilities in your application than when using a default policy.

Editing a Custom Policy

You can edit a custom policy at any time by opening the file up in a text editor, making the required changes, and saving the file. You will also need to validate your file and upload it to the ShiftLeft repository.