@yourclaw/clawguard-scanner

Security scanner orchestrator for AI agent skills. This package coordinates multiple scanning tools in parallel, scores severity, and produces structured reports.

---

Installation

npm install @yourclaw/clawguard-scanner

For local development as part of the ClawGuard project:

cd ../clawguard && make setup

---

Usage

Programmatic

import { scanSkill } from "@yourclaw/clawguard-scanner";

const report = await scanSkill("/path/to/skill", {
  builtinOnly: false,       // set true to skip external tools
  skipAi: true,             // skip AI review
  format: "json",           // json | markdown | sarif
});

console.log(report.status);        // "passed" | "warning" | "blocked"
console.log(report.severityScore); // 0-100
console.log(report.findings);      // Finding[]

Via the CLI

npx @yourclaw/clawguard-cli scan /path/to/skill
npx @yourclaw/clawguard-cli scan /path/to/skill --builtin-only --skip-ai
npx @yourclaw/clawguard-cli scan /path/to/skill --format sarif

---

Scanner Adapters

The scanner runs multiple tools in parallel using Promise.allSettled for graceful degradation. If an external tool is not installed, that scanner is skipped without failing the overall scan.

Adapter	Tool	What it scans	Required?
Builtin Pattern Matcher	@yourclaw/clawguard-rules	Prompt injection, secrets, malware, permissions	Built-in
Gitleaks	gitleaks	Hardcoded secrets & credentials	Optional
Semgrep	semgrep	Custom code patterns (eval, shell injection)	Optional
MCP-Scan	mcp-scan	MCP server configuration issues	Optional
npm audit	npm	Known CVEs in dependencies	Optional
AI Review	Claude API	Ambiguous cases needing judgement	Optional

Check which tools are installed

npx @yourclaw/clawguard-cli doctor

---

Severity Scoring

Findings are scored on a 0–100 scale with category-based multipliers:

Category	Multiplier
Prompt injection	2.0x
Malware	1.5x
Secrets	1.2x
Permissions	1.0x

Individual severity weights:

Severity	Points
critical	25
high	15
medium	8
low	3

The final score is capped at 100.

Score → Recommendation

Score	Status	Recommendation
0	passed	install
1–30	warning	install_with_warning
31–70	warning	prompt_user
71+	blocked	block

---

Report Formats

JSON (--format json)

Full machine-readable report with all findings, metadata, and scores.

Markdown (--format markdown)

Human-readable report suitable for GitHub issues or PR comments.

SARIF (--format sarif)

SARIF 2.1.0 format for integration with GitHub Code Scanning, VS Code, and other SARIF-compatible tools.

---

Suppressing Findings (.clawguard-ignore)

The scanner supports a .clawguard-ignore JSON file for suppressing known false positives. Place it in your skill directory (or any parent directory) and the scanner will automatically discover it by walking up the directory tree.

This feature was introduced to support the YourClaw OpenClaw fork upstream sync pipeline, where automated scans of upstream releases can surface false positives that need to be documented and suppressed transparently. See PR #4 for the initial set of suppressions and the analysis behind each one.

You can also pass an explicit path via the ignoreFile option:

const report = await scanSkill("/path/to/skill", {
  ignoreFile: "/path/to/.clawguard-ignore",
});

// Suppressed findings are still available for auditing
console.log(report.suppressed);        // Finding[] (what was filtered out)
console.log(report.suppressionCount);  // number

File format

{
  "suppressions": [
    {
      "id": "unique-id-for-this-suppression",
      "rule": "the-rule-name-or-finding-id",
      "file": "path/fragment/to/match",
      "scanner": "semgrep",
      "justification": "Why this is a false positive",
      "addedBy": "your-name",
      "addedAt": "2026-03-02",
      "reference": "https://github.com/your-org/your-repo/pull/123"
    }
  ]
}

Field reference

Field	Required	Description
id	Yes	Unique identifier for this suppression entry
rule	Yes	Must match the finding's name or id field
file	Yes	Substring match against the finding's file path
scanner	Yes	Which scanner produced the finding (semgrep, clawguard-rules, gitleaks, etc.)
justification	Yes	Explanation of why this finding is a false positive
addedBy	Yes	Person or bot that added the suppression
addedAt	Yes	Date the suppression was added (ISO 8601 date)
reference	No	URL to the PR, issue, or discussion that discovered and analyzed the finding

Matching logic

A finding is suppressed when both conditions are true:

1. suppression.rule equals the finding's name or id
2. The finding's file path contains suppression.file as a substring

Audit trail

Every suppression should include a reference URL pointing to the PR or issue where the finding was discovered, analyzed, and confirmed as a false positive. This creates a transparent audit trail so that anyone reviewing suppressions can understand the full context behind each decision.

For automated pipelines (e.g. upstream sync workflows), the reference should link to the sync PR that first flagged the finding — giving future reviewers a direct path to the scan results, code analysis, and team discussion.

When to suppress vs. when to fix

Use suppressions only for confirmed false positives — cases where the scanner flags code that is actually safe. If a finding points to a real issue, fix the code instead of suppressing it.

Good reasons to suppress:

• A shell: true flag is used safely with hardcoded arguments (no user input)
• A unicode escape sequence is used for data formatting, not obfuscation
• A regex pattern triggers a secrets scanner but is not an actual secret

Bad reasons to suppress:

• The finding is inconvenient to fix right now
• You disagree with the rule's severity (file an issue on the rule instead)

---

Key Types

interface Finding {
  id: string;           // e.g. "PI-001"
  severity: "critical" | "high" | "medium" | "low";
  category: string;     // e.g. "prompt-injection"
  message: string;
  file?: string;
  line?: number;
  scanner: string;      // which adapter found it
}

interface ScanReport {
  status: "passed" | "warning" | "blocked";
  severityScore: number;
  recommendation: string;
  findings: Finding[];
  metadata: SkillMetadata;
  scannedAt: string;
}

---

Development

# Install dependencies
npm install

# Run tests
npm run test:run        # single run
npm test                # watch mode

# Build
npm run build

# Lint
npm run lint

Adding a new scanner adapter

1. Create src/scanners/my-adapter.ts.
2. Implement the adapter function returning Finding[].
3. Use isCommandAvailable() from utils.ts for graceful skip.
4. Register in src/orchestrator.ts inside scannerTasks.
5. Add tests in test/.

---

Makefile

make install    # npm install
make build      # tsup build
make test       # vitest run
make lint       # biome check
make clean      # remove dist/ and node_modules/

---

Contributing

See the main CONTRIBUTING.md for guidelines. The scanner is a great place to contribute new integrations — each adapter is a self-contained file in src/scanners/.

---

License

Apache-2.0