Skip to content

cli.md

Latest commit

 

History

History
175 lines (125 loc) · 4.06 KB

cli.md

File metadata and controls

175 lines (125 loc) · 4.06 KB
Raw

gsast-cli

Command-line HTTP client for interacting with a running gsast-api server. Submits scan requests, polls scan status, and retrieves SARIF results.

Package name: gsast-cli
Python import root: gsast_cli
Location: gsast-cli/
Entry point binary: gsast

Installation

Install standalone (no server-side dependencies required):

pip install -e gsast-core/ -e gsast-cli/

After installation the gsast command is available in $PATH.

Configuration file

The CLI reads ~/.gsast.json by default. Use --config to override the path.

{
  "api_secret_key": "your-server-api-key",
  "base_url": "https://your-gsast-server.com",
  "target": {
    "provider": "github|gitlab",
    "organizations": ["your-org"],
    "groups": ["your-group"]
  },
  "filters": {
    "is_archived": false,
    "is_fork": false,
    "is_personal_project": false,
    "max_repo_mb_size": 500,
    "last_commit_max_age": 365,
    "ignore_path_regexes": ["test", "examples"],
    "must_path_regexes": []
  },
  "scanners": ["semgrep", "trufflehog", "dependency-confusion"]
}

If ~/.gsast.json does not exist it is created automatically with placeholder values on the first run.

Commands

gsast scan [OPTIONS] [RULE_PATHS...]

Start a new scan. Rule files or directories are uploaded to the server.

# Scan with custom Semgrep rules
gsast scan rules/sg_custom/

# Override filters at scan time
gsast scan \
  --max-repo-mb-size 100 \
  --is-archived false \
  --last-commit-max-age 30 \
  rules/sg_custom/

# Scan specific GitLab groups
gsast scan \
  --group-ids "security,development" \
  --group-include-subgroups true \
  rules/sg_custom/secrets/

Options:

Flag Type Description
--is-archived bool Filter out archived repositories
--is-fork bool Filter out forked repositories
--is-personal-project bool Filter out personal projects
--max-repo-mb-size int Maximum repository size in MB
--ignore-path-regexes text Comma-separated path regexes to exclude
--must-path-regexes text Comma-separated path regexes to require
--group-ids text GitLab group IDs (comma-separated)
--group-with-shared bool Include projects shared with the group
--group-include-subgroups bool Include subgroup projects
--scan-secrets bool Enable full git history clone for TruffleHog
--last-commit-max-age int Skip repos with no commit in this many days

gsast info SCAN_ID

Get status of a specific scan.

gsast info SCAN-2024-01-01-12-00-00

gsast scans-status

List all known scan IDs and their statuses.

gsast scans-status

gsast results SCAN_ID [OPTIONS]

Retrieve SARIF results for a completed scan.

# All results
gsast results SCAN-2024-01-01-12-00-00

# Filter by project
gsast results SCAN-2024-01-01-12-00-00 --project my-repo

# Filter by scanner
gsast results SCAN-2024-01-01-12-00-00 --scan dependency-confusion

# JSONPath extraction
gsast results SCAN-2024-01-01-12-00-00 --query '$..properties.packageName'

# Combine filters
gsast results SCAN-2024-01-01-12-00-00 \
  --project my-repo \
  --scan semgrep \
  --query '$..results[*].ruleId'

gsast scanners

List scanner plugins registered on the server.

gsast scanners

gsast cleanup-queues

Delete all pending and finished job queues.

gsast cleanup-queues

gsast cleanup-projects

Clear the cached project list in Redis.

gsast cleanup-projects

Global options

Flag Description
--config PATH Path to config file (default: ~/.gsast.json)
--help Show help 
gsast --config /path/to/custom.json scan rules/

Scan ID format

Scan IDs are generated by the server and follow the format SCAN-YYYY-mm-dd-HH-MM-SS-fff-xxxx, where fff is milliseconds and xxxx is a random hex suffix. The millisecond and random components ensure that scans started at the same time do not collide. Treat the scan ID as an opaque identifier.