Security Scanner - Background Agent

A comprehensive security scanning agent for vulnerabilities and secrets detection

Quick Start • Documentation • Dashboard • Contributing

Overview

A background agent that monitors source changes in git repositories and automatically runs security scans to find vulnerabilities and secrets. Supports multiple scanners (Grype, Trivy, Syft), secret detection (Entropy, Gitleaks, Trufflehog), VS Code extension, Claude Code hooks, and a web-based security dashboard.

Key Capabilities

Multiple vulnerability scanners: Grype, Trivy, or run all scanners together
Secret detection: Built-in entropy scanner + Gitleaks + Trufflehog support
SBOM generation: Generate Software Bill of Materials with Syft
Security Dashboard: Web-based analytics with posture scoring
Real-time file watching with configurable debounce interval
Dual platform support: VS Code extension + Claude Code hooks

Quick Start

# Clone and install
git clone https://github.com/sudogit/securityagent.git
cd securityagent
pnpm install

# Install security tools (grype, trivy, syft, gitleaks, trufflehog)
pnpm setup

# Build
pnpm build

# Run tests
pnpm test

# Run a security scan
pnpm scan

# Start the security dashboard
pnpm dashboard

Architecture

System Context

C4Context
    title System Context Diagram - Security Scanner Agent

    Person(dev, "Developer", "Uses security scanning tools")
    Person(seceng, "Security Engineer", "Reviews security posture")

    System(scanner, "Security Scanner Agent", "Monitors repositories and scans for vulnerabilities and secrets")

    System_Ext(grype, "Grype", "Vulnerability Scanner")
    System_Ext(trivy, "Trivy", "Security Scanner")
    System_Ext(syft, "Syft", "SBOM Generator")
    System_Ext(gitleaks, "Gitleaks", "Secret Scanner")
    System_Ext(trufflehog, "Trufflehog", "Secret Scanner")
    System_Ext(vscode, "VS Code", "IDE")
    System_Ext(claude, "Claude Code", "AI Assistant")

    Rel(dev, scanner, "Runs scans, views dashboard")
    Rel(seceng, scanner, "Reviews posture, analyzes trends")
    Rel(scanner, grype, "Executes vulnerability scans")
    Rel(scanner, trivy, "Executes vulnerability scans")
    Rel(scanner, syft, "Generates SBOM")
    Rel(scanner, gitleaks, "Scans for secrets")
    Rel(scanner, trufflehog, "Scans for secrets")
    Rel(vscode, scanner, "Extension integration")
    Rel(claude, scanner, "Hook integration")

High-Level Architecture

graph TB
    subgraph "User Interfaces"
        CLI[("CLI<br/>Command Line")]
        VSC[("VS Code<br/>Extension")]
        CC[("Claude Code<br/>Hooks")]
        DASH[("Dashboard<br/>Web UI")]
    end

    subgraph "Core Services"
        SM[["Scanner Manager<br/>Orchestration & Deduplication"]]
        FW[["File Watcher<br/>Change Detection"]]
        CF[["Config Loader<br/>Settings Management"]]
    end

    subgraph "Vulnerability Scanners"
        GS["Grype Scanner"]
        TS["Trivy Scanner"]
        SS["Syft Scanner"]
    end

    subgraph "Secret Scanners"
        ES["Entropy Scanner<br/>(Built-in)"]
        GL["Gitleaks Scanner"]
        TH["Trufflehog Scanner"]
    end

    subgraph "Dashboard Services"
        PC[["Posture Calculator<br/>Security Scoring"]]
        ST[["Scan Storage<br/>History & Analytics"]]
        WS[["Web Server<br/>REST API"]]
    end

    subgraph "External Tools"
        GRYPE[("Grype CLI")]
        TRIVY[("Trivy CLI")]
        SYFT[("Syft CLI")]
        GITLEAKS[("Gitleaks CLI")]
        TRUFFLEHOG[("Trufflehog CLI")]
    end

    CLI --> SM
    VSC --> SM
    CC --> SM
    DASH --> WS

    SM --> GS
    SM --> TS
    SM --> SS
    SM --> ES
    SM --> GL
    SM --> TH

    FW --> SM
    CF --> SM

    GS --> GRYPE
    TS --> TRIVY
    SS --> SYFT
    GL --> GITLEAKS
    TH --> TRUFFLEHOG

    SM --> ST
    ST --> PC
    PC --> WS

    style SM fill:#4CAF50,color:#fff
    style PC fill:#2196F3,color:#fff
    style ES fill:#FF9800,color:#fff
    style DASH fill:#9C27B0,color:#fff

Package Architecture (C4 Container)

graph TB
    subgraph "securityagent Monorepo"
        subgraph "@securityagent/core"
            direction TB
            SM2["ScannerManager"]
            FW2["FileWatcher"]
            GS2["GrypeScanner"]
            TS2["TrivyScanner"]
            SY2["SyftScanner"]

            subgraph "secrets/"
                ES2["EntropyScanner"]
                GL2["GitleaksScanner"]
                TH2["TrufflehogScanner"]
                PT["patterns.ts<br/>30+ regex patterns"]
                EN["entropy.ts<br/>Shannon entropy"]
            end
        end

        subgraph "@securityagent/dashboard"
            direction TB
            DS["DashboardServer<br/>Express + REST API"]
            SS2["ScanStorage<br/>JSON persistence"]
            PC2["PostureCalculator<br/>Polynomial scoring"]
            UI["Web UI<br/>Chart.js"]
        end

        subgraph "@securityagent/claude-hooks"
            direction TB
            IDX["CLI Entry Point"]
            PTU["PostToolUse Hook"]
            SST["SessionStart Hook"]
            SC["scan.ts"]
            WC["watch.ts"]
            DC["dashboard.ts"]
        end

        subgraph "@securityagent/vscode-extension"
            direction TB
            EXT["extension.ts"]
            SMG["ScanManager"]
            SB["StatusBar"]
            OC["OutputChannel"]
        end
    end

    SM2 --> GS2
    SM2 --> TS2
    SM2 --> SY2
    SM2 --> ES2
    SM2 --> GL2
    SM2 --> TH2

    ES2 --> PT
    ES2 --> EN

    DS --> SS2
    SS2 --> PC2

    IDX --> SC
    IDX --> WC
    IDX --> DC
    SC --> SM2
    DC --> DS

    EXT --> SMG
    SMG --> SM2
    SMG --> SB
    SMG --> OC

    style SM2 fill:#4CAF50,color:#fff
    style PC2 fill:#2196F3,color:#fff
    style ES2 fill:#FF9800,color:#fff
    style DS fill:#9C27B0,color:#fff

Scanning Flow

sequenceDiagram
    autonumber
    participant U as User/Hook
    participant CLI as CLI/Extension
    participant SM as ScannerManager
    participant VS as VulnScanner
    participant SS as SecretScanner
    participant ST as Storage
    participant PC as PostureCalc

    U->>CLI: Run scan command
    CLI->>SM: scan(options)

    par Vulnerability Scan
        SM->>VS: scan(path)
        VS->>VS: Execute Grype/Trivy
        VS-->>SM: VulnResults[]
    and Secret Scan
        SM->>SS: scanSecrets(path)
        SS->>SS: Pattern matching + Entropy
        SS-->>SM: SecretResults[]
    end

    SM->>SM: Deduplicate results
    SM-->>CLI: Combined results

    opt Store Results
        CLI->>ST: storeScan(results)
        ST->>PC: calculate(input)
        PC-->>ST: PostureScore
    end

    CLI-->>U: Display results

Security Posture Calculation

graph LR
    subgraph "Input Metrics"
        V["Vulnerabilities<br/>C/H/M/L counts"]
        S["Secrets<br/>C/H/M/L counts"]
        A["Scan Age<br/>Hours since last scan"]
        C["Coverage<br/>Scanners used"]
    end

    subgraph "Polynomial Formula"
        F["Score = 100 - Σ(penalties)"]
        VP["Vuln Penalty<br/>Wc×C² + Wh×H^1.5 + Wm×M + Wl×√L"]
        SP["Secret Penalty<br/>Higher weights than vulns"]
        AP["Age Penalty<br/>0-10 based on freshness"]
        CP["Coverage Penalty<br/>0-10 based on scanner %"]
    end

    subgraph "Output"
        SC["Score<br/>0-100"]
        GR["Grade<br/>A/B/C/D/F"]
        RC["Recommendations"]
    end

    V --> VP
    S --> SP
    A --> AP
    C --> CP

    VP --> F
    SP --> F
    AP --> F
    CP --> F

    F --> SC
    SC --> GR
    SC --> RC

    style F fill:#4CAF50,color:#fff
    style SC fill:#2196F3,color:#fff

Dashboard Data Flow

flowchart TB
    subgraph "Data Collection"
        SC1[Vulnerability Scan] --> |Results| ST[(Scan Storage)]
        SC2[Secret Scan] --> |Results| ST
        SC3[SBOM Generation] --> |Results| ST
    end

    subgraph "Analytics Engine"
        ST --> |Historical Data| PC[Posture Calculator]
        PC --> |Score + Trends| AN[Analytics]
    end

    subgraph "Web Dashboard"
        AN --> |JSON API| WS[Express Server]
        WS --> |REST| API["/api/*"]
        WS --> |HTML| UI[Dashboard UI]

        subgraph "Pages"
            UI --> P1["/ Overview"]
            UI --> P2["/vulnerabilities"]
            UI --> P3["/secrets"]
        end
    end

    subgraph "Visualizations"
        P1 --> CH1["Posture Score Gauge"]
        P1 --> CH2["Trend Line Chart"]
        P1 --> CH3["Scanner Usage Pie"]
        P2 --> TBL1["Vulnerability Table"]
        P3 --> TBL2["Secrets Table"]
    end

    style PC fill:#4CAF50,color:#fff
    style WS fill:#9C27B0,color:#fff
    style ST fill:#FF9800,color:#fff

Supported Scanners

Scanner	Type	Description	Install Required
Grype	Vulnerability	Fast vulnerability scanner for container images and filesystems	Yes
Trivy	Vulnerability	Comprehensive security scanner for containers, filesystems, and code	Yes
Syft	SBOM	Software Bill of Materials (SBOM) generator	Yes
Entropy	Secret	Built-in high-entropy string and pattern detection	No
Gitleaks	Secret	Git-aware secret scanner with extensive rule sets	Yes
Trufflehog	Secret	Secret scanner with verification capabilities	Yes

Quick Status Check

pnpm scan:status

Project Structure

graph TB
    subgraph "Root"
        R["securityagent/"]
        PKG["package.json"]
        WS["pnpm-workspace.yaml"]
        SC["scripts/install-tools.sh"]
    end

    subgraph "packages/"
        subgraph "core/"
            C1["scanner/"]
            C2["watcher/"]
            C3["config/"]
            C4["tests/ (79)"]
        end

        subgraph "dashboard/"
            D1["server/"]
            D2["storage/"]
            D3["analytics/"]
            D4["tests/ (25)"]
        end

        subgraph "claude-hooks/"
            H1["hooks/"]
            H2["cli/"]
        end

        subgraph "vscode-extension/"
            V1["src/"]
            V2["ui/"]
        end
    end

    R --> PKG
    R --> WS
    R --> SC
    R --> C1
    R --> D1
    R --> H1
    R --> V1

📁 Full Directory Structure

securityagent/
├── package.json                 # Root package with workspace scripts
├── pnpm-workspace.yaml          # pnpm monorepo configuration
├── LICENSE                      # MIT License
├── scripts/
│   └── install-tools.sh         # Installs all security tools
│
├── packages/
│   ├── core/                    # @securityagent/core
│   │   ├── src/
│   │   │   ├── scanner/
│   │   │   │   ├── ScannerManager.ts
│   │   │   │   ├── GrypeScanner.ts
│   │   │   │   ├── TrivyScanner.ts
│   │   │   │   ├── SyftScanner.ts
│   │   │   │   └── secrets/
│   │   │   │       ├── EntropyScanner.ts
│   │   │   │       ├── GitleaksScanner.ts
│   │   │   │       ├── TrufflehogScanner.ts
│   │   │   │       ├── patterns.ts
│   │   │   │       └── entropy.ts
│   │   │   └── watcher/
│   │   │       └── FileWatcher.ts
│   │   └── tests/               # 79 tests
│   │
│   ├── dashboard/               # @securityagent/dashboard
│   │   ├── src/
│   │   │   ├── server/DashboardServer.ts
│   │   │   ├── storage/ScanStorage.ts
│   │   │   └── analytics/PostureCalculator.ts
│   │   └── tests/               # 25 tests
│   │
│   ├── claude-hooks/            # @securityagent/claude-hooks
│   │   └── src/
│   │       ├── index.ts
│   │       ├── hooks/
│   │       └── cli/
│   │
│   └── vscode-extension/        # VS Code Extension
│       └── src/
│           ├── extension.ts
│           └── ScanManager.ts

Features

Secret Detection Patterns

The built-in entropy scanner detects 30+ secret types:

mindmap
  root((Secret Patterns))
    Cloud Providers
      AWS Access Keys
      AWS Secret Keys
      GCP API Keys
      Azure Credentials
    Version Control
      GitHub PAT
      GitHub OAuth
      GitLab Tokens
    Databases
      MongoDB URI
      PostgreSQL URI
      MySQL URI
      Redis URI
    Services
      Slack Tokens
      Stripe Keys
      SendGrid Keys
      Twilio Keys
    Generic
      API Keys
      Passwords
      Private Keys
      JWT Tokens

Configuration

Project Configuration File

Create .gryperc.json in your project root:

{
  "enabled": true,
  "scanner": "grype",
  "secretScanner": "entropy",
  "debounceMs": 2000,
  "minSeverity": "low",
  "scanTimeout": 300000,
  "generateSBOM": false,
  "sbomFormat": "json"
}

Option	Type	Default	Description
`enabled`	boolean	`true`	Enable/disable automatic scanning
`scanner`	string	`"grype"`	Vulnerability scanner: `grype`, `trivy`, or `all`
`secretScanner`	string	`"entropy"`	Secret scanner: `entropy`, `gitleaks`, `trufflehog`, or `all`
`debounceMs`	number	`2000`	Debounce interval (500-30000ms)
`minSeverity`	string	`"low"`	Minimum severity to report

Usage

NPM Scripts

Command	Description
`pnpm build`	Build all packages
`pnpm test`	Run all 104 tests
`pnpm scan`	Run vulnerability scan
`pnpm scan:secrets`	Run secret scan
`pnpm scan:all`	Run all scanners
`pnpm scan:status`	Show scanner status
`pnpm scan:watch`	Watch mode
`pnpm dashboard`	Start web dashboard

CLI Commands

# Vulnerability scanning
security-scan scan                              # Grype (default)
security-scan scan --scanner trivy              # Trivy
security-scan scan --scanner all                # All scanners

# Secret scanning
security-scan scan --secrets                    # Entropy (built-in)
security-scan scan --secrets --secret-scanner gitleaks
security-scan scan --secrets --secret-scanner all

# Combined
security-scan scan --scanner all --secrets --secret-scanner all

# Dashboard
security-scan dashboard                         # localhost:3847
security-scan dashboard --port 8080             # Custom port

Security Dashboard

Starting the Dashboard

pnpm dashboard
# Opens at http://localhost:3847

Dashboard Features

Feature	Description
Security Posture Score	0-100 score with letter grades (A-F)
Trend Charts	30-day posture history visualization
Vulnerability Summary	Breakdown by severity
Secret Summary	Detected secrets by type
Recommendations	Actionable improvement suggestions

API Endpoints

Endpoint	Description
`GET /api/posture`	Current security posture score
`GET /api/scans`	Recent scan history
`GET /api/scans/:id`	Detailed scan results
`GET /api/stats`	Aggregate statistics
`GET /api/history`	Posture trend history

VS Code Extension

Commands

Command	Description
`Security Scanner: Start Monitoring`	Start file watching
`Security Scanner: Stop Monitoring`	Stop file watching
`Security Scanner: Run Scan Now`	Run vulnerability scan
`Security Scanner: Scan for Secrets`	Run secret detection
`Security Scanner: Generate SBOM`	Generate SBOM
`Security Scanner: Show Status`	Show scanner status

Claude Code Hooks

Create .claude/settings.json:

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Write|Edit",
      "hooks": [{
        "type": "command",
        "command": "node \"$CLAUDE_PROJECT_DIR/packages/claude-hooks/dist/index.js\" post-tool-use"
      }]
    }],
    "SessionStart": [{
      "matcher": ".*",
      "hooks": [{
        "type": "command",
        "command": "node \"$CLAUDE_PROJECT_DIR/packages/claude-hooks/dist/index.js\" session-start"
      }]
    }]
  }
}

Testing

# Run all tests (104 total)
pnpm test

# Package-specific
cd packages/core && pnpm test      # 79 tests
cd packages/dashboard && pnpm test # 25 tests

Package	Tests	Coverage
@securityagent/core	79	Scanners, patterns, entropy
@securityagent/dashboard	25	Posture calculator, storage
Total	104

Troubleshooting

🔧 Scanner Not Found

# Install all tools
pnpm setup

# Or manually
brew install grype syft trivy gitleaks trufflehog

🔧 Dashboard Not Starting

Check port 3847 is available
Try custom port: pnpm dashboard --port 8080
Rebuild: pnpm build

🔧 Tests Failing

pnpm clean && pnpm build && pnpm test

License

MIT License - see LICENSE file.

Contributing

Fork the repository
Create a feature branch
Make changes with tests
Run pnpm test (104 tests must pass)
Submit a pull request

Built with ❤️ for secure software development

Report Bug • Request Feature

Name		Name	Last commit message	Last commit date
Latest commit History 7 Commits
.claude		.claude
packages		packages
scripts		scripts
.gitignore		.gitignore
.gryperc.json.example		.gryperc.json.example
LICENSE		LICENSE
QUICKSTART.md		QUICKSTART.md
README.md		README.md
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
tsconfig.base.json		tsconfig.base.json

Folders and files

Latest commit

History

Repository files navigation

Security Scanner - Background Agent

Overview

Key Capabilities

Quick Start

Architecture

System Context

High-Level Architecture

Package Architecture (C4 Container)

Scanning Flow

Security Posture Calculation

Dashboard Data Flow

Supported Scanners

Quick Status Check

Project Structure

Features

Secret Detection Patterns

Configuration

Project Configuration File

Usage

NPM Scripts

CLI Commands

Security Dashboard

Starting the Dashboard

Dashboard Features

API Endpoints

VS Code Extension

Commands

Claude Code Hooks

Testing

Troubleshooting

License

Contributing

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages