Configure scans

A sentinel.yml file in the folder you scan changes what DL Sentinel looks at and when a scan fails. Every key is optional. Without the file, built-in defaults apply.

Create a config file

1. In the root of the project, create a file named sentinel.yml (sentinel.yaml also works).

2. Add only the keys you want to change. For example, to fail only on critical findings:

   policy:
     failOn: [critical]

3. Run a scan. DL Sentinel finds the file by itself:

   sentinel scan .

To use a config file stored somewhere else, pass it explicitly:

sentinel scan ./project --config ./ci/sentinel.yml

If the file has an error, the scan stops with exit code 64 and a message. Keys DL Sentinel does not know produce a warning, not an error.

A complete example

include:
  - '**/*'
exclude:
  - '**/node_modules/**'
maxFileSizeBytes: 1048576
scanners:
  secrets:
    enabled: true
    allowlist: []
    ignorePaths: []
  dependencies:
    dataSource: none
    advisoryDbPath: null
policy:
  failOn: [critical, high]
suppress:
  - rule: S008
    path: '**/*.test.env'
    reason: fake keys used in tests
    expires: 2027-01-01
  - id: 9f2c4a1b8d3e6f70
    reason: accepted risk, tracked in TICKET-123

Every key is listed in the reference.

Choose which files are scanned

include and exclude are lists of glob patterns, matched against each file's path relative to the scanned folder:

• ** matches any number of folders, * matches within one folder name, ? matches one character.
• {a,b} matches either a or b. A trailing / matches a whole folder.
• A leading ! re-includes something an earlier pattern excluded. The last pattern that matches a path decides.
• Dotfiles such as .env are matched like any other file.

If you set exclude, your list replaces the default list. The defaults are:

**/node_modules/**
**/.git/**
**/dist/**
**/build/**
**/out/**
**/coverage/**
**/.next/**
**/.venv/**
**/venv/**
**/__pycache__/**
**/target/debug/**
**/target/release/**
**/.dl-sentinel/**
**/*.min.js
**/*.min.css
**/*.map

Files larger than maxFileSizeBytes (default 1 MiB) are skipped, and so are binary files and symbolic links.

Turn a scanner off

scanners:
  smart-contract:
    enabled: false

Each scanner has an enabled key. The secrets and dependencies scanners have extra settings, described in The scanners.

Set when a scan fails

policy.failOn lists the severities that make a scan exit with code 1. The default is [critical, high].

policy:
  failOn: [critical, high, medium]

To change it for one run only, use --fail-on:

sentinel scan . --fail-on critical

Suppress findings

Suppression hides findings you have reviewed and accepted. Suppressed findings disappear from the report and the counts, and the report shows how many were suppressed.

Each suppress entry can match on:

Key	Matches
rule	A rule id, such as S001
scanner	A scanner id, such as secrets
path	A file glob, such as '**/*.test.env'
id	One finding, by its stable id

Two more keys are not used for matching:

Key	Purpose
reason	Why you suppressed it, for whoever reads the file next
expires	A date such as 2027-01-01. From that date the entry stops working and the findings come back

How entries match:

• Inside one entry, every key you give must match. rule: S008 with path: '**/*.test.env' hides S008 only in those files.
• A finding is hidden if any entry matches it.
• An entry with no rule, scanner, path or id matches nothing, so a half-written entry cannot hide everything.
• A broken entry is skipped with a warning; the scan still runs.

TIP

Always add reason and expires. An expiry date makes accepted risks come back for review instead of staying hidden for good.

Which setting wins

From highest to lowest:

1. Options on the command line, such as --scanners and --fail-on. They apply to that run only.
2. A file given with --config.
3. sentinel.yml or sentinel.yaml in the scanned folder.
4. Built-in defaults.

WARNING

A sentinel.yml inside a repository you scan is part of that repository. If you scan code from someone else, check its sentinel.yml first, or pass your own with --config, because the file can exclude paths or suppress findings.

Next steps

• Baselines
• Use DL Sentinel in CI
• Command reference