Comment on page

Customizing rules

How to define and customize lstn rules

lstn allows you to define and customize rules to filter verdicts and apply behaviors such as blocking or ignoring based on specific criteria. Rules can be used to enforce policies, automate workflows, and improve security practices. A classic use case for this is blocking CI in case of a violation (such as the detection of known malicious behavior).
See rules list for a pre-defined set of rules that work out of the box for common use cases.
Defining rule-based policies
Rules are defined in a YAML file, typically named rules.yml. Each rule consists of the following attributes:
name: A unique name for the rule.
query: A jq query expression that filters verdicts based on specified conditions.
behavior (optional): The behavior to apply to verdicts that match the rule. Possible values are "block" and "ignore." If not specified, the default behavior is "block."
For example:
  - name: ignore_priority_medium
    query: .[] | select(.verdicts[]?.priority == "medium")
    behavior: ignore

Since rules are jq expressions at the core, they can be easily customized and adapted to your use case. For a list of useful jq expressions that can be used to define policies, see the section on Filtering output.


Policy example: Halt CI if priority level is critical
The below expression would output only the verdicts where priority level is critical, and exit with status code of 1 if found
lstn in <project path> --json -q '.[] | select(.verdicts[].priority == "critical") | halt_error(1)'
An expression such as this allows users to invoke certain actions upon receiving an exit code, such as stopping a build from proceeding in case a risky dependency is detected.

Last modified 8mo ago