Comment on page
Policy (alpha)
How to define rule-based policy controls using lstn
This is a private preview (alpha) feature. Please contact us if you would like to try it out or need support.
One of the primary motivations behind
lstn is to provide developers and teams the controls to ensure that the packages they use in their codebase are secure before they get shipped into production applications. We achieve this through our policy engine, which allows for assertions to be defined on a behavioural level.
In this guide, we will cover key concepts for the policy engine and demonstrate how the output of lstn workflows can be used to define and compose rules.
listen.dev allows you to create programmatic rule-based policies which can be asserted on the output of scans. A classic use case for this is blocking CI in case of a violation (such as the detection of known malicious behavior).
Rules are typically defined in the
rules.yml file in your repository, which the policy action uses as a manifest. Tip:
💡
lstn comes with a pre-defined set of rules that work out of the box for blocking and ignoring common use cases.To enforce policy through
lstn, make sure you have added the following step in your lstn.yml workflow file in GitHub:jobs:
steps:
- name: Enforce lstn policy
uses: garnet-org/[email protected]
with:
workdir: '.'
apply-policy: true
rules-file: 'rules.yml'
rule-name: 'ignore_priority_medium'
Secondly, you will need the
rules.yml file in the root of your GitHub repo. This contains the rules to be asserted, for example:rules:
- name: block_priority_medium
query: .[] | select(.verdicts[]?.priority == "medium")
- name: ignore_priority_medium
query: .[] | select(.verdicts[]?.priority == "medium")
behavior: ignore
- CI will proceed in this case, but you'll be able to view outputs of scan.
- In the below example, the "Enforce lstn Policy" step shows that the "ignore_priority_medium" rule was exercised by lstn, and it also displays the alerts which invoked this behaviour. While medium priority alerts were detected, CI wasn't blocked.
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.
- CI will be blocked in this case, and exit with an error code of 1.
- In the below example, the "Enforce lstn Policy" step shows that the "block_priority_medium" rule was exercised by lstn. CI was stopped in this case.
Tip: the recommended usage for policy is to use the rule "block_priority_critical". This will ensure that CI doesn't get blocked in case of medium priority alerts, but only those that are categorized as "critical" by listen.dev
💡
Last modified 7mo ago