Troubleshooting and FAQ
Common questions and problems, with their causes and fixes.
Installing and running
sentinel: command not found
The source build does not put sentinel on your path. Either run node apps/cli/dist/main.js from the dl-sentinel folder, or add the alias shown on the install page. Open a new terminal after editing ~/.bashrc.
The build fails or the command prints syntax errors
DL Sentinel needs Node.js 20 or later. Check with node --version, update Node.js, then run npm install and npm run build again.
Is there a .deb, .rpm or snap?
Not for version 0.1.0. The project contains packaging for .deb, .rpm and Arch, but the 0.1.0 release has no package files attached. There is no snap or Flatpak. Watch the releases page.
Does it work on Windows or macOS?
Only Linux on x64 and arm64 is tested.
Scans and results
The scan exits with code 1. Did it crash?
No. 1 means the scan worked and found at least one finding at a severity in policy.failOn (critical and high by default). A crash or internal error is 2, and a wrong command or bad config file is 64.
The terminal shows counts but no details
That is how the terminal format works. Use --format markdown --output report.md or --format json to see each finding. See Read and act on findings.
Every dependency shows "check skipped" (D002)
No vulnerability data source is set, which is the default. DL Sentinel reports that it did not check rather than pretending your dependencies are safe. Set scanners.dependencies.dataSource: osv in sentinel.yml to check against the public OSV database (this uses the internet), or file with advisoryDbPath for a local advisory file.
A finding is a false alarm
Check the code first. If it really is safe, add a suppress entry to sentinel.yml with a reason, matching on the rule id and a path, or on the finding's id. See Suppress findings.
A suppressed finding came back
Its suppression entry has an expires date that has passed. That is on purpose: review the finding again, then set a new date or fix it.
A file I expected to be scanned was skipped
Check that it is not under a default exclude such as dist/ or build/, not larger than 1 MiB, not a binary file and not a symbolic link. Symbolic links are never followed. Change include, exclude or maxFileSizeBytes in sentinel.yml if needed.
No findings. Is my code secure?
No tool can say that. DL Sentinel's rules are tuned to report less rather than guess, so it misses things. Use it as one check among several, alongside code review and testing.
Can I scan someone else's repository?
Scan code you own or have permission to test. Scanning only reads files and does not attack anything, but a report lists weaknesses. If you scan a repository from someone else, be aware that its own sentinel.yml can exclude files or suppress findings; pass your own file with --config to be sure.
Does my code leave my machine?
No. Scans are offline unless you choose dataSource: osv, which sends dependency names and versions to OSV. The GitHub Action calls only the GitHub API, to post its comment. The server sends notifications only to channels you add.
Will DL Sentinel run code from the repository?
No. It never runs scanned code or repository scripts, and it never loads plugins from sentinel.yml. Plugins load only when you pass --plugin yourself.
Server and dashboard
The dashboard says it is unauthorized
Open Settings, paste a valid token into API Token and select Save. If you started the server without SENTINEL_API_TOKEN, it printed a new token at startup, and that token changes on every restart. Set SENTINEL_API_TOKEN to keep the same one.
A scan request is refused with a validation error
The path must be an absolute path inside SENTINEL_SCAN_ROOT. In Docker, that is a path under /scans that you mounted in compose.yaml.
Findings for a scan return 409
The scan has not finished yet. Check its status with GET /api/scans/<id> and try again when it is completed.
The server will not start and mentions a plugin
A plugin in SENTINEL_PLUGINS failed to load. The server refuses to start rather than report results for a scanner that never ran. Fix or remove the plugin spec.
Reporting problems
- Bugs and questions: GitHub issues.
- A security problem in DL Sentinel itself: do not open a public issue. Use a private security advisory.