Wraith

Wraith is Ghost Security Agent's dependency scanner. It scans lockfiles for known vulnerabilities using the OSV database, supporting every major package ecosystem with offline mode and license scanning.

Architecture

Wraith wraps osv-scanner, Google's open-source vulnerability scanner, with a streamlined CLI and Go library interface. When you scan a lockfile:

1. Wraith parses the lockfile to extract all packages and versions
2. Each package is queried against the OSV database for known vulnerabilities
3. Results include CVE identifiers, severity scores (CVSS), affected version ranges, and available fixes
4. Output is formatted for the requested format (text, JSON, or Markdown)

The OSV database aggregates vulnerabilities from multiple sources: the National Vulnerability Database, GitHub Security Advisories, and ecosystem-specific databases.

Key features

• Multi-ecosystem support -- Go, npm, PyPI, Ruby, Rust, Java, PHP, .NET, Dart, and more
• Offline mode -- download the vulnerability database once, scan without network access
• License scanning -- detect dependency licenses and check against an allowlist
• Multiple output formats -- colored text, JSON, and Markdown
• Go library -- use Wraith programmatically in your own tools

CLI reference

Commands

wraith scan

Scan a lockfile for known vulnerabilities.

wraith scan [flags] <lockfile>

wraith download-db

Download or refresh the local vulnerability database for offline scanning.

wraith download-db

wraith version

Show version information.

wraith version

Examples

# Scan a Go module
wraith scan go.mod

# Scan with JSON output for CI/CD
wraith scan --format json package-lock.json

# Generate a Markdown report
wraith scan --output report.md Gemfile.lock

# Offline scanning (download database first)
wraith download-db
wraith scan --offline go.mod

# Scan with license checking
wraith scan --licenses go.mod

# Check licenses against an allowlist
wraith scan --license-allowlist MIT,Apache-2.0,BSD-3-Clause go.mod

Output formats

Text (default) -- colored terminal output with package grouping:

─────────────────────────────────
SCAN SUMMARY
─────────────────────────────────
Packages scanned: 47
Vulnerabilities: 3
Affected packages: 2

● lodash 4.17.20 (npm)
  └─ GHSA-xxxx-yyyy-zzzz
     Prototype pollution in lodash
     CVEs: CVE-2024-XXXXX

● express 4.17.1 (npm)
  └─ GHSA-aaaa-bbbb-cccc
     Open redirect vulnerability
     CVEs: CVE-2024-YYYYY
  └─ GHSA-dddd-eeee-ffff
     Path traversal via malformed URLs
     CVEs: CVE-2024-ZZZZZ

JSON -- structured output with full vulnerability details:

{
  "package_count": 47,
  "vulnerability_count": 3,
  "results": [
    {
      "package": "lodash",
      "version": "4.17.20",
      "ecosystem": "npm",
      "found_vulnerabilities": [
        {
          "id": "GHSA-xxxx-yyyy-zzzz",
          "summary": "Prototype pollution in lodash",
          "severity": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H",
          "cves": ["CVE-2024-XXXXX"],
          "references": ["https://github.com/advisories/..."]
        }
      ]
    }
  ]
}

Markdown -- report format with summary table, vulnerability details, and references.

Exit codes

• 0 -- no vulnerabilities or license violations found
• 1 -- vulnerabilities or license violations found

Supported lockfiles

Wraith automatically detects the ecosystem from the lockfile format.

Offline mode

For air-gapped environments or deterministic CI pipelines:

# Download the database (requires network)
wraith download-db

# Scan without network access
wraith scan --offline go.mod

The local database is stored in the system's standard cache location. Refresh it at any time with wraith download-db.

To download and scan in a single command:

wraith scan --offline --download-db go.mod

License scanning

Wraith can scan dependency licenses alongside vulnerabilities:

# Show license summary
wraith scan --licenses go.mod

# Check against an allowlist
wraith scan --license-allowlist MIT,Apache-2.0 go.mod

When using an allowlist, any package with a license not on the list is flagged as a violation. License violations trigger the same exit code 1 as vulnerabilities, making it easy to use in CI/CD gates.

Skill integration

When used through the scan-deps skill, Wraith's vulnerability data feeds into AI exploitability analysis. The skill assesses each CVE against your actual codebase: Is the vulnerable function called? Can user input reach it? Is this a production dependency? See Dependency scanning for details.