DHIVA LABS · LEARN

Appearance

Beginner guide ​

In about ten minutes you scan a deliberately insecure sample project, read the summary, open the full report and learn what the exit code means. Then you scan a project of your own.

What you need ​

  • DL Sentinel built from source, with the sentinel alias set up. See Install.
  • A terminal open in the dl-sentinel folder.

The source code includes two small sample projects under tests/fixtures/. vulnerable-app contains at least one planted problem for every scanner. clean-app is the same kind of project written safely. All the credentials in them are fake. They are safe targets to practise on, because they exist to be scanned.

Run your first scan ​

  1. Scan the vulnerable sample:

    bash
    sentinel scan tests/fixtures/vulnerable-app

  2. While it runs, a few progress lines appear: the folder being scanned, the number of files found, an OK line for each scanner with its finding count and time, and a closing Completed in ... line.

  3. Then the summary report is printed.

Read the summary ​

The summary has four parts, top to bottom:

PartWhat it tells you
DL Sentinel v0.1.0 and Scanning:The version, and the full path of the folder that was scanned
One line per scannerHow many findings each scanner reported, for example secrets followed by a count
Critical: to Info:How many findings there are at each severity
Scan completed.The scan finished. Any scanner that failed is listed above this line under Scanner errors:

Severity says how bad a problem would be if it is real: critical, high, medium, low or info. See Read and act on findings for what each level means.

The summary shows counts only. To see each finding, ask for a full report.

Check the exit code ​

Every scan ends with an exit code. Print it straight after the scan:

bash
echo $?
text
1

1 means the scan found at least one finding at a severity that fails the policy. By default those severities are critical and high. A scan with none of them exits 0. The full list:

CodeMeaning
0Scan finished and the policy passed
1Findings at a failing severity were found
2The scan or the tool hit an error
64The command was used wrongly, for example an unknown option

CI systems use this code to pass or fail a build. See Use DL Sentinel in CI.

Open the full report ​

  1. Write a Markdown report to a file:

    bash
    sentinel scan tests/fixtures/vulnerable-app --format markdown --output report.md

  2. Open report.md in any text editor or Markdown viewer.

The report starts with a summary table, then has one section per finding, most severe first. Each section heading has the severity, the rule id and a title, for example CRITICAL S001, then the file and line, the confidence, a description, the evidence with any secret replaced by [REDACTED], and a recommendation.

TIP

Keep reports out of version control. Add report.md and other report files to your .gitignore. A report contains no secret values, but it is a list of weaknesses in your code.

Compare with the clean sample ​

bash
sentinel scan tests/fixtures/clean-app

Far fewer findings appear, and no critical or high ones. The few that remain are mostly info notes. For example, the dependencies scanner reports that it did not check for vulnerable versions, because no vulnerability data source is set up yet. That is DL Sentinel being honest rather than guessing.

Scan your own project ​

  1. Change to a project folder that you own or may test:

    bash
    cd ~/projects/my-app

  2. Scan it:

    bash
    sentinel scan .

    The . means "this folder".

  3. Write the full report and read it:

    bash
    sentinel scan . --format markdown --output ~/my-app-report.md

DL Sentinel skips common generated folders such as node_modules, .git, dist and build, and files over 1 MiB. You can change this with a sentinel.yml file. See Configure scans.

What you learned ​

  • sentinel scan <folder> runs every scanner and prints a summary of counts.
  • --format markdown --output <file> writes every finding with its file, line and advice.
  • The exit code is 1 when findings at a failing severity are present.
  • Secrets in reports are always shown as [REDACTED].

Next steps ​