Comment on page
Integration guide

This guide describes the integration steps needed to run scanning and policy workflows in CI using lstn.
The following walkthrough provides guidance on integrating the lstn GitHub action into an existing CI pipeline.  
-> Scanning workflow 
Below is an example of a scenario using listendev/action to run a scan a project in GitHub. 
Pre-requisites
A GitHub repository for your project
A package.json file
A workflow file in .github/workflows directory
Step 1: Add scan to an existing workflow file
Add the below code block to an existing workflow file in .github/workflows directory to run the lstn action workflow. 
    # Checks out the project to be scanned
    uses: actions/checkout@v3
​
    steps:    
      - name: Run lstn scan
        uses: listendev/[email protected]
​
    # continue to install dependencies...
​
The above example assumes that your package.json file is present in the GitHub project root. If it is present in a subdirectory (e.g. src) then the workdir path should be adjusted accordingly (see configuration options). For example:

    steps:    
        uses: listendev/[email protected]
        with:
          - workdir: "./src"
On each pull request and subsequent commit, lstn will run and add comments to the PR where lstn has failed (once per commit).
Step 2: Viewing scan results
If a scan executes successfully, you will see output in two ways:
1.In a GitHub Pull Request comment, in case the workflow is triggered on a PR. The comment will only be added once per commit, displaying the most recent results. .
​
example PR comment
2.in CI logs (for all events)

To see expected outputs, see Viewing results.
 Woot! 🎉
 At this point, you should have the lstn scanning workflow set up and running in your CI pipeline.
​


The below functionality is in alpha preview. Please contact us for support.
-> Policy enforcement workflow (optional)
The below scenario uses garnet-org/lstn-policy Github action to enforce policy on a JavaScript project located in a GitHub repository. The action is listed on the GitHub marketplace.
Pre-requisites
A GitHub repository for your project
A package.json file
A workflow file in .github/workflows directory containing the policy stub (see below)
A rules.yml file in the root of your GitHub project (see below)
Step 1: Add the policy action to the workflow file 

To run the action with policy, you would need to add the code block provided below to your existing YAML workflow file after the scanning step.
​
      - name: lstn policy
        uses: garnet-org/lstn-[email protected]
        with:
          rule-name: 'ignore_priority_medium'
          
In the above example, the rule applied is 'ignore_priority_medium'. This is a common setting in which medium verdicts will be recognized, but CI won't be blocked. It is recommended that you block the verdicts with critical priority. 

Additionally, you will need to include a rules.yml file in your project repository, also provided below. To understand how this works in detail, refer to Policy (alpha).
Step 1: Add the rules.yml file 
The rules.yml file contains a set of rules that are used to enforce policies on your project's dependencies. 

This file is required to be present in the root of your GitHub project. Below is an example you can use:
rules:
  - name: block_priority_medium
    query: .[] | select(.verdicts[]?.priority == "medium")
​
  - name: ignore_priority_medium
    query: .[] | select(.verdicts[]?.priority == "medium")
    behavior: ignore
​
  - name: block_priority_critical
    query: .[] | select(.verdicts[]?.priority == "critical")
​
  - name: block_network_connection
    query: .[] | .verdicts[]? | select(.message == "unexpected outbound connection destination")
​
  - name: ignore_network_connection
    query: .[] | .verdicts[] | select(.message == "unexpected outbound connection destination")
    behavior: ignore
​
  - name: block_process_spawn
    query: .[] | .verdicts[]? | select(.message == "npm install spawned a process")
​
  - name: ignore_process_spawn
    query: .[] | .verdicts[]? | select(.message == "npm install spawned a process")
    behavior: ignore
For investigating results of policy enforcement, see this section.
Last modified 4mo ago