ghost-scan-deps

Original source / Raw SKILL.md

---
name: "ghost-scan-deps"
description: |
  Ghost Security - Software Composition Analysis (SCA) scanner. Scans dependency lockfiles for known vulnerabilities, identifies CVEs, and generates findings with severity levels and remediation guidance. Use when the user asks about dependency vulnerabilities, vulnerable packages, CVE checks, security audits of dependencies, or wants to scan lockfiles like package-lock.json, yarn.lock, go.sum, or Gemfile.lock.
allowed-tools: Read, Glob, Grep, Bash, Task, TodoRead, TodoWrite
argument-hint: "[path-to-scan]"
license: apache-2.0
metadata:
  version: 1.1.0
---

# Ghost Security SCA Scanner — Orchestrator

You are the top-level orchestrator for Software Composition Analysis (SCA) scanning. Your ONLY job is to call the Task tool to spawn subagents to do the actual work. Each step below gives you the exact Task tool parameters to use. Do not do the work yourself.

## Defaults

- **repo_path**: the current working directory
- **scan_dir**: `~/.ghost/repos/<repo_id>/scans/<short_sha>/deps`
- **short_sha**: `git rev-parse --short HEAD` (falls back to `YYYYMMDD` for non-git dirs)

$ARGUMENTS

Any values provided above override the defaults.

---

## Execution

1. **Setup** — compute paths and create output directories
2. **Initialize Wraith** — install the wraith binary
3. **Discover Lockfiles** — find all dependency lockfiles in the repo
4. **Scan for Vulnerabilities** — run wraith against each lockfile
5. **Analyze Candidates** — assess exploitability of each candidate
6. **Summarize Results** — generate the final scan report

### Step 0: Setup

Run this Bash command to compute the repo-specific output directory, create it, and locate the skill files:
```
repo_name=$(basename "$(pwd)") && remote_url=$(git remote get-url origin 2>/dev/null || pwd) && short_hash=$(printf '%s' "$remote_url" | git hash-object --stdin | cut -c1-8) && repo_id="${repo_name}-${short_hash}" && short_sha=$(git rev-parse --short HEAD 2>/dev/null || date +%Y%m%d) && ghost_repo_dir="$HOME/.ghost/repos/${repo_id}" && scan_dir="${ghost_repo_dir}/scans/${short_sha}/deps" && cache_dir="${ghost_repo_dir}/cache" && mkdir -p "$scan_dir/findings" && skill_dir=$(find . -path '*skills/scan-deps/SKILL.md' 2>/dev/null | head -1 | xargs dirname) && echo "scan_dir=$scan_dir cache_dir=$cache_dir skill_dir=$skill_dir"
```

Store `scan_dir` (the absolute path under `~/.ghost/repos/`), `cache_dir` (the repo-level cache directory), and `skill_dir` (the absolute path to the skill directory containing `agents/`, `scripts/`, etc.).

After this step, your only remaining tool is Task. Do not use Bash, Read, Grep, Glob, or any other tool for Steps 1–5.

### Step 1: Initialize Wraith

Call the Task tool to initialize the wraith binary:
```json
{
  "description": "Initialize wraith binary",
  "subagent_type": "general-purpose",
  "prompt": "You are the init agent. Read and follow the instructions in <skill_dir>/agents/init/agent.md.\n\n## Inputs\n- skill_dir: <skill_dir>"
}
```

The init agent installs wraith to `~/.ghost/bin/wraith` (or `wraith.exe` on Windows).

### Step 2: Discover Lockfiles

Call the Task tool to discover lockfiles in the repository:
```json
{
  "description": "Discover lockfiles",
  "subagent_type": "general-purpose",
  "prompt": "You are the discover agent. Read and follow the instructions in <skill_dir>/agents/discover/agent.md.\n\n## Inputs\n- repo_path: <repo_path>\n- scan_dir: <scan_dir>"
}
```

The discover agent finds all lockfiles (go.mod, package-lock.json, etc.) and writes `<scan_dir>/lockfiles.json`.

**If lockfile count is 0**: Skip to Step 5 (Summarize) with no lockfiles found.

### Step 3: Scan for Vulnerabilities

Call the Task tool to run the wraith scanner:
```json
{
  "description": "Scan for vulnerabilities",
  "subagent_type": "general-purpose",
  "prompt": "You are the scan agent. Read and follow the instructions in <skill_dir>/agents/scan/agent.md.\n\n## Inputs\n- repo_path: <repo_path>\n- scan_dir: <scan_dir>"
}
```

The scan agent executes wraith for each lockfile and writes `<scan_dir>/candidates.json`.

**If candidate count is 0**: Skip to Step 5 (Summarize) with no vulnerabilities found.

### Step 4: Analyze Candidates

Call the Task tool to analyze the vulnerability candidates:
```json
{
  "description": "Analyze vulnerability candidates",
  "subagent_type": "general-purpose",
  "prompt": "You are the analysis agent. Read and follow the instructions in <skill_dir>/agents/analyze/agent.md.\n\n## Inputs\n- repo_path: <repo_path>\n- scan_dir: <scan_dir>\n- skill_dir: <skill_dir>\n- cache_dir: <cache_dir>"
}
```

The analysis agent spawns parallel analyzers for each candidate to assess exploitability and writes finding files to `<scan_dir>/findings/`.

### Step 5: Summarize Results

Call the Task tool to summarize the findings:
```json
{
  "description": "Summarize scan results",
  "subagent_type": "general-purpose",
  "prompt": "You are the summarize agent. Read and follow the instructions in <skill_dir>/agents/summarize/agent.md.\n\n## Inputs\n- repo_path: <repo_path>\n- scan_dir: <scan_dir>\n- skill_dir: <skill_dir>\n- cache_dir: <cache_dir>"
}
```

After executing all the tasks, report the scan results to the user.

---

## Error Handling

If any Task call fails, retry it **once**. If it fails again, stop and report the failure.


---

## Skill Companion Files

> Additional files collected from the skill directory layout.

### README.md

```markdown
# Ghost SCA Scanner

AI-powered Software Composition Analysis (SCA) scanner that detects exploitable vulnerabilities in your dependencies. Uses [wraith](https://github.com/ghostsecurity/wraith) for vulnerability detection with AI analysis to filter false positives.

## What Makes This Different

Traditional SCA tools report every CVE found in your dependency tree, leading to alert fatigue. **Ghost SCA uses AI to analyze each vulnerability and determine if it's actually exploitable** in your codebase.

**Key Features**:
- Scans all major package ecosystems (Go, npm, PyPI, RubyGems, Cargo, Maven, Composer)
- AI-powered exploitability analysis filters false positives
- Traces user input to vulnerable code paths
- Detects mitigating controls and configuration
- Provides actionable remediation guidance

## Usage

```
/ghost-scan-deps [path-to-scan]
```

Examples:
```
/ghost-scan-deps .                    # Scan current directory
/ghost-scan-deps ./backend            # Scan specific directory
/ghost-scan-deps /path/to/repo        # Scan absolute path
```

The scanner will automatically discover all lockfiles in the repository.

## How It Works

1. **Initialize**: Downloads/verifies wraith binary (includes osv-scanner)
2. **Discover**: Finds all dependency lockfiles in your repository
3. **Scan**: Runs wraith to detect vulnerabilities from OSV database (500,000+ CVEs)
4. **Analyze**: AI agents evaluate each vulnerability for:
   - Is the vulnerable package/function actually used?
   - Can user input reach the vulnerable code?
   - Is this production code or test-only?
   - Are there mitigating controls in place?
5. **Report**: Generates detailed findings only for exploitable vulnerabilities

## Prerequisites

The skill requires the `wraith` binary. It will be installed automatically via one of two methods:

### Option 1: GitHub Releases (default)

If the [wraith repository](https://github.com/ghostsecurity/wraith) is reachable, the binary is downloaded automatically from GitHub releases.

### Option 2: Local Fallback

If GitHub is unavailable (network issues, air-gapped environment), place release artifacts in the fallback directory:

| Platform | Fallback Directory |
|----------|-------------------|
| Linux/macOS | `~/.ghost/releases/latest/` |
| Windows | `%USERPROFILE%\.ghost\releases\latest\` |

Required files (for your platform):
```
~/.ghost/releases/latest/
├── wraith_linux_amd64.tar.gz
├── wraith_linux_arm64.tar.gz
├── wraith_darwin_amd64.tar.gz
├── wraith_darwin_arm64.tar.gz
└── wraith_windows_amd64.zip
```

You only need the file for your platform. Each archive contains both `wraith` and `osv-scanner` binaries.

## Supported Platforms

- Linux (amd64, arm64)
- macOS (amd64/Intel, arm64/Apple Silicon)
- Windows (amd64) - via Git Bash, WSL, or MSYS2

## Supported Ecosystems

The scanner automatically detects and scans these lockfile formats:

**Go**:
- `go.mod`, `go.sum`

**JavaScript/TypeScript (npm)**:
- `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`

**Python**:
- `uv.lock`, `poetry.lock`, `Pipfile.lock`, `requirements.txt`

**Ruby**:
- `Gemfile.lock`

**Rust**:
- `Cargo.lock`

**Java/Kotlin**:
- `pom.xml`, `gradle.lockfile`

**PHP**:
- `composer.lock`

## Output

Results are saved to `~/.ghost/repos/<repo_id>/scans/<short_sha>/deps/`:
```
~/.ghost/repos/myrepo-a1b2c3d4/scans/abc1234/deps/
├── lockfiles.json        # Discovered lockfiles
├── scan-1.json           # Raw wraith output (per lockfile)
├── scan-2.json
├── candidates.json       # All vulnerabilities detected
├── findings/             # Exploitable vulnerabilities only
│   └── <finding-id>.md
└── report.md             # Comprehensive summary report
```

## Example Output

```
## Scan Summary
- Lockfiles Scanned: 2
- Packages Scanned: 145
- Vulnerabilities Detected: 12 (raw)
- Confirmed Findings: 3 (exploitable)
- False Positives Filtered: 9 (75%)

### Top Findings
1. HIGH: [email protected] - CVE-2020-8203 - Exploitable via /api/settings
2. HIGH: [email protected] - CVE-2020-28168 - SSRF in webhook handler
3. MEDIUM: [email protected] - CVE-2021-44906 - Prototype pollution in CLI parser
```

## False Positive Filtering

The AI analyzer filters vulnerabilities that are:
- **Not actually used**: Package imported but vulnerable function not called
- **Test/dev dependencies only**: Not included in production builds
- **Effectively mitigated**: Validation wrappers, WAF rules, configuration changes
- **Version overrides**: Using patched fork despite lockfile version

## Remediation Guidance

Each exploitable finding includes:
- Specific upgrade commands for your package manager
- Testing checklist for affected functionality
- Alternative remediation if upgrade not possible
- Estimated effort (hours/days)
- Links to CVE details and advisories

Example:
```bash
# Go
go get golang.org/x/[email protected]
go mod tidy

# npm
npm install [email protected]
npm audit

# Python (poetry)
poetry add [email protected]
poetry lock
```

## Severity Levels

The scanner uses contextual severity based on exploitability:

- **HIGH**: Actively exploitable, user input reaches vulnerable code
- **MEDIUM**: Exploitable with certain conditions or limited impact
- **LOW**: Theoretical vulnerability, difficult to exploit or minimal impact

Base CVSS scores are adjusted based on actual exploitability in your codebase.

## Privacy & Security

- All analysis happens locally - no code or vulnerability data sent to external services
- Only OSV database lookups are performed by wraith (standard practice)
- No telemetry or usage tracking
- Findings stay in your `~/.ghost/` directory

## Offline Mode

For air-gapped environments, wraith supports offline scanning:

1. Download vulnerability database once:
   ```bash
   wraith download-db
   ```

2. Scan using local database:
   ```bash
   wraith scan --offline go.mod
   ```

The skill can be configured to use offline mode if needed.

## Integration with CI/CD

To integrate into your CI/CD pipeline:

1. Install the skill in your CI environment
2. Run scans on every PR or commit
3. Fail builds on HIGH severity findings
4. Generate reports as artifacts

Example GitHub Actions:
```yaml
- name: Run SCA Scan
  run: claude-code /ghost-scan-deps

- name: Check for HIGH findings
  run: |
    if grep -q "Severity: HIGH" ~/.ghost/repos/*/scans/*/deps/report.md; then
      echo "HIGH severity vulnerabilities found!"
      exit 1
    fi
```

## Limitations

- Requires lockfiles to be committed (doesn't scan based on manifest files alone)
- Analysis quality depends on code readability and complexity
- May require manual review for complex data flows
- Initial scan may take several minutes on large repositories

## Troubleshooting

**No lockfiles found**:
- Ensure lockfiles are committed to version control
- Check that you're using supported package managers
- Verify you're scanning the correct directory

**Installation fails**:
- Check network access to github.com/ghostsecurity/wraith
- Try local fallback method (see Prerequisites)
- Verify platform support (Linux/macOS/Windows)

**Too many false positives**:
- The AI analysis should filter most false positives automatically
- If you see genuine false positives, they may need manual configuration
- Consider using custom osv-scanner.toml to ignore specific vulnerabilities

## Learn More

- [Wraith Documentation](https://github.com/ghostsecurity/wraith)
- [OSV Database](https://osv.dev)
- [Ghost Security](https://ghost.security)

---

*Powered by Wraith and AI Exploitability Analysis*

```