User guide for defect scanners#

Tools based on DefectScanner can be used to:

  • Discover software defects with security implications, i.e. software vulnerabilities.

  • Verify each vulnerability is reachable and impacts security.

  • Triage the severity of each vulnerability based on its likelihood and impact.

  • File an issue for each vulnerability in a secure Buganizer component.

  • Attempt to create a “proof of concept” (PoC) that demonstrates the vulnerability.

  • Attempt to create a fix for the vulnerability.

For more detail on how such tools can be implemented, see the Implementation guide for defect scanners.

Example workflows#

Users run the defect scanner from the command line:

# Run a full scan across the entire repository
$ bazelisk run //path/to:my_defect_scanner

# Scan specific source files and print findings
$ bazelisk run //path/to:my_defect_scanner -- \
    -s /path/to/my/project \
    -f "pw_status/**" "pw_string/**"

# Scan, create bug reports, and upload candidate fixes
$ bazelisk run //path/to:my_defect_scanner -- \
    -s /path/to/my/project -b -u

# Re-generate fixes for an existing bug ID
$ bazelisk run //path/to:my_defect_scanner -- \
    -s /path/to/my/project \
    -w /path/to/working/dir -i 123456789 -u

# Run a full scan across the entire repository
$ python3 my_defect_scanner.py

# Scan specific source files and print findings
$ python3 my_defect_scanner.py -s /path/to/my/project \
    -f "pw_status/**" "pw_string/**"

# Scan, create bug reports, and upload candidate fixes
$ python3 my_defect_scanner.py -s /path/to/my/project -b -u

# Re-generate fixes for an existing bug ID
$ python3 my_defect_scanner.py -s /path/to/my/project \
    -w /path/to/working/dir -i 123456789 -u

Sample output#

To be added soon…

Command-line arguments reference#

Since DefectScanner is derived from Scanner, it automatically provides a uniform set of command-line arguments:

orphan:

Argument

Description

Associated stages

-s, --src-repo PATH

Path to a local read-only Git repository workspace to scan. If omitted, the scanner automatically clones the remote repo_url into <working-dir>/src.

Emitter Analyzer

-d, --dst-repo PATH

Path to a local writable Git repository workspace where code editors apply patches and commit changes. If omitted, the scanner clones repo_url into <working-dir>/dst.

Code Editor

-f, --files [FILES...]

One or more specific file paths or glob patterns to scan instead of enumerating the full repository.

Emitter

-i, --issue ID

Issue ID to process (can be specified multiple times). Providing issue IDs disables the Emitter and analyzer stages; the IssueReader fetches the specified issues from the issue tracker and injects them directly into the code editor.

IssueReader

-l, --hotlist ID

Hotlist ID to process (can be specified multiple times). Providing hotlist IDs disables file enumeration and analyzer stages, querying the issue tracker for all issues on the hotlist and injecting them into the code editor.

IssueReader

-b, --create-bugs

If enabled, creates Buganizer issues for findings. Otherwise, issue details are printed to stdout (defaults to False).

IssueWriter

-e, --allow-edits

If enabled, creates or updates local Git revisions and runs validation builds (defaults to False).

Code Editor

-u, --allow-uploads

If enabled, uploads candidate commits to Gerrit as Change Lists (implies -e / --allow-edits; defaults to False).

Code Editor

-r, --resume

Resumes an interrupted run. Reuses existing intermediate files in stage directories (*_in, *_out) and picks up enumeration from last_emitted.txt where it stopped, rather than cleaning the working directory.

All stages.

-m, --max-retries COUNT

Maximum number of retries for transient errors (network timeouts, subprocess failures) before moving a failed item to the stage’s *_err/ directory (defaults to 3).

All stages.

-w, --working-dir PATH

Working directory for intermediate results and stage queues (defaults to /tmp/<program_name>). Each stage maintains isolated *_in, *_out, and *_err subdirectories.

All stages.

-o, --output PATH

Path to write the final results as a CSV file, in addition to printing formatted tabular results to stdout.

Collector

-v, --verbose

If enabled, prints verbose diagnostic output and detailed issue information to stdout (defaults to False).

All stages.