{ "markdown": "

\n \"Shield\"\n

\n\n

\n Security orchestration for code editor CLIs.
\n Autonomous pentests. Static analysis. Secrets scanning. Dependency audits. One command.\n

\n\n

\n \"License:\n \"Version\n \"Shield\n \"GitHub\n

\n\n

One command. Full security posture. Actionable fixes.

\n\n---\n\n## What Shield Does\n\nShield detects your tech stack, runs every applicable security scanner in parallel, consolidates findings into a single report, calculates a risk score, proposes code fixes, and optionally files GitHub issues -- all without leaving your editor.\n\n```\n +-------------------+\n | Shannon Pentest | Proof-by-exploitation, real PoCs\n +-------------------+\n | Semgrep SAST | 82 custom rules + community rulesets\nYour Code --> detect-stack.sh --| gitleaks Secrets | Full git history scan\n | Dependency Audit | npm / pip / composer audit\n | Freshness Check | Outdated dependency detection\n +-------------------+\n |\n consolidate.sh\n |\n calculate-score.sh\n |\n +----------------+----------------+\n | | |\n Risk Scorecard Fix Proposals GitHub Issues\n (0-100) (ready diffs) (per finding)\n```\n\n## Quick Start\n\n```bash\n# 1. Clone and install security tools\ngit clone https://github.com/alissonlinneker/shield-claude-skill.git\ncd shield-claude-skill && ./install.sh\n\n# 2. Register the marketplace in Claude Code (run inside Claude Code)\n/plugin marketplace add /path/to/shield-claude-skill\n\n# 3. Install the plugin\n/plugin install shield@shield-security\n\n# 4. Open any project and run\n/shield:shield\n```\n\nOr for quick testing without marketplace registration:\n\n```bash\nclaude --plugin-dir /path/to/shield-claude-skill\n# Then inside Claude Code:\n/shield:shield\n```\n\n## Features\n\n| Category | Capability | Details |\n|----------|-----------|---------|\n| **Pentest** | Autonomous penetration testing | Full attack-surface analysis via Shannon -- proof-by-exploitation with real PoC payloads |\n| **SAST** | Static application security testing | Semgrep with 82 custom rules (12 JS/TS, 11 Python, 11 PHP, 10 Go, 10 Ruby, 8 Rust, 10 Java, 10 C#) plus community rulesets |\n| **Secrets** | Secrets scanning | gitleaks detection across entire git history -- keys, tokens, passwords |\n| **SCA** | Dependency vulnerability audit | Supports 12 package managers: npm, yarn, pnpm, bun, pip, composer, go, bundler, cargo, maven, gradle, dotnet -- auto-detected by lock file |\n| **Freshness** | Dependency outdated check | Detects packages behind on MAJOR, MINOR, and PATCH versions |\n| **Scoring** | Security scorecard | Weighted 0-100 risk score with severity breakdown |\n| **Remediation** | Fix proposals | Generates before/after diffs you can apply directly |\n| **Baselines** | Scan comparison | Tracks improvements and regressions between scans |\n| **Issues** | GitHub issue creation | Files issues with severity labels, CWE references, and compliance mappings |\n| **SARIF** | Standard output format | SARIF export for GitHub Security tab integration |\n| **Compliance** | Compliance mapping | Maps findings to SOC 2, PCI-DSS, and HIPAA controls |\n| **Zero-config** | Stack detection | Automatically identifies languages, frameworks, package managers, Docker presence |\n| **Resilience** | Graceful degradation | Runs whichever tools are installed, skips the rest, notes gaps in report |\n\n## Real Output Examples\n\n### Example 1 -- Quick Scan on a Node.js Project\n\n```\nStack detected: JavaScript, TypeScript, Next.js, React (pnpm)\n\nSecurity Score: 0/100 — CRITICAL RISK\n[ ] 0/100\n\n| Severity | Count |\n|----------|-------|\n| CRITICAL | 1 |\n| HIGH | 20 |\n| MEDIUM | 5 |\n| LOW | 3 |\n\nTop findings:\n [CRITICAL] SHIELD-001: fast-xml-parser regex injection bypass (CWE-185)\n Package: fast-xml-parser | Fix: Update to 4.4.1+\n [HIGH] SHIELD-002: brace-expansion ReDoS (CWE-1333)\n Package: brace-expansion | Fix: Update to 2.0.1+\n [HIGH] SHIELD-003: tar hardlink path traversal (CWE-22)\n Package: tar | Fix: Update to 6.2.1+\n [HIGH] SHIELD-004: micromatch ReDoS via recursive patterns (CWE-1333)\n Package: micromatch | Fix: Update to 4.0.8+\n\nOutdated dependencies: 47 packages behind latest\n MAJOR: 12 packages (breaking changes, potential security risk)\n MINOR: 18 packages (may include security fixes)\n PATCH: 17 packages (bug fixes, security patches)\n```\n\n### Example 2 -- Clean Scan on a PHP Project\n\n```\nStack detected: PHP, Laravel, Composer, Docker\n\nSecurity Score: 100/100 — LOW RISK\n[##############################] 100/100\n\n| Severity | Count |\n|----------|-------|\n| CRITICAL | 0 |\n| HIGH | 0 |\n| MEDIUM | 0 |\n| LOW | 0 |\n\nNo vulnerabilities found across all scanners.\nAll dependencies are up to date.\n```\n\n### Example 3 -- Consolidated JSON Output\n\n```json\n{\n \"findings\": [\n {\n \"id\": \"SHIELD-001\",\n \"severity\": \"CRITICAL\",\n \"title\": \"SQL Injection in UserRepository\",\n \"cwe\": \"CWE-89\",\n \"owasp\": \"A03:2021\",\n \"source_tool\": \"semgrep\",\n \"file\": \"src/repositories/user.ts\",\n \"line\": 45,\n \"evidence\": \"db.query(`SELECT * FROM users WHERE id = ${req.params.id}`)\",\n \"recommendation\": \"Use parameterized queries\",\n \"status\": \"new\"\n }\n ],\n \"metadata\": {\n \"scan_date\": \"2026-03-11\",\n \"scan_timestamp\": \"2026-03-11T14:30:00Z\",\n \"tools_used\": [\"semgrep\", \"gitleaks\", \"npm-audit\"],\n \"tools_skipped\": [\"shannon\"],\n \"total_files_scanned\": 142\n },\n \"summary\": {\n \"total\": 29,\n \"by_severity\": { \"critical\": 1, \"high\": 20, \"medium\": 5, \"low\": 3 },\n \"by_tool\": { \"semgrep\": 8, \"gitleaks\": 0, \"npm-audit\": 21 },\n \"by_cwe\": { \"CWE-89\": 1, \"CWE-1333\": 5, \"CWE-22\": 3 }\n }\n}\n```\n\n### Example 4 -- Security Scorecard Breakdown\n\n```json\n{\n \"score\": 45,\n \"max_score\": 100,\n \"risk_level\": \"HIGH\",\n \"breakdown\": {\n \"critical\": { \"count\": 1, \"weight\": 15, \"deduction\": 15 },\n \"high\": { \"count\": 3, \"weight\": 8, \"deduction\": 24 },\n \"medium\": { \"count\": 4, \"weight\": 3, \"deduction\": 12 },\n \"low\": { \"count\": 4, \"weight\": 1, \"deduction\": 4 }\n },\n \"total_deduction\": 55,\n \"total_findings\": 12\n}\n```\n\n## Modes\n\n| Mode | Command | Description |\n|------|---------|-------------|\n| **Full** | `/shield:shield full` | Complete assessment -- Shannon pentest + SAST + secrets + SCA + freshness + scorecard |\n| **Quick** | `/shield:shield quick` | Fast scan -- SAST + secrets + dependency audit + freshness (no pentest) |\n| **Fix** | `/shield:shield fix` | Auto-remediation -- analyzes findings and generates ready-to-apply diffs |\n| **Verify** | `/shield:shield verify` | Re-scan after fixes -- confirms issues are resolved, compares against baseline |\n| **Score** | `/shield:shield score` | Scorecard only -- calculates risk score from last scan or fresh data |\n| **Outdated** | `/shield:shield outdated` | Dependency freshness check -- lists all outdated packages by severity tier |\n| **Audit** | `/shield:audit` | Intelligence analysis -- attack chains, false positives, logic vulns, IaC review. No tools required |\n\n## Security Auditor — Intelligence Layer\n\nShield runs the tools. The Security Auditor provides the brain.\n\n```\n/shield:shield quick # Step 1: scan with tools\n/shield:audit # Step 2: deep analysis with reasoning\n```\n\nOr use the auditor standalone on any file — no scan needed:\n\n```\n/shield:audit src/auth.py # Code audit\n/shield:audit Dockerfile # IaC security review\n/shield:audit terraform/ # Infrastructure review\n```\n\n### What Shield vs Security Auditor covers\n\n| Capability | `/shield:shield` | `/shield:audit` |\n|-----------|:-:|:-:|\n| Semgrep SAST (82 rules) | Runs the tool | Confirms, explains, provides full fix code |\n| Secrets (git history) | gitleaks scan | Inline + config file detection |\n| Dependency CVEs | npm/pip/composer audit | Explains exploitability context |\n| Autonomous pentest | Shannon | Manual reasoning layer |\n| IaC security (Docker/k8s/Terraform/CI) | -- | Full checklist-based review |\n| Logic vulnerabilities (IDOR, race conditions) | -- | Business logic analysis |\n| Architecture / threat model | -- | Trust boundaries, attack surface mapping |\n| Attack chain narrative | -- | End-to-end exploitation story |\n| False positive analysis | -- | Context-aware confirmation |\n| No tools required | Needs installs | Works anywhere |\n\n### Score adjustment\n\nWhen the auditor runs after Shield, it adjusts the risk score:\n\n```\nShield score: 62/100\nLogic vulnerabilities: -15 (1 IDOR found, not detectable by Semgrep)\nFalse positives removed: +8 (SHIELD-023, SHIELD-031 confirmed FP)\nAdjusted score: 55/100 — HIGH RISK\n```\n\n### Reference files (loaded on demand)\n\n| File | When loaded | Content |\n|------|------------|---------|\n| `owasp-top10.md` | Application code analysis | OWASP Top 10 2021 with CWEs and vulnerable/fixed code patterns |\n| `iac-checklist.md` | Dockerfile, k8s, Terraform, GitHub Actions, nginx | Security checklists by severity tier |\n| `crypto-guidance.md` | Crypto issues (passwords, JWT, TLS, AES, keys) | Algorithm selection, code examples, common mistakes |\n\n## Prerequisites\n\n| Tool | Required | Purpose | Install |\n|------|----------|---------|---------|\n| [Semgrep](https://semgrep.dev/) | Recommended | Static analysis (SAST) | `brew install semgrep` or `pip install semgrep` |\n| [gitleaks](https://github.com/gitleaks/gitleaks) | Recommended | Secrets scanning | `brew install gitleaks` |\n| [jq](https://jqlang.github.io/jq/) | Required | JSON processing for consolidation | `brew install jq` |\n| [Trivy](https://trivy.dev/) | Optional | Container and IaC scanning | `brew install trivy` |\n| [Shannon](https://github.com/KeygraphHQ/shannon) | Optional | Autonomous penetration testing | `git clone` + Docker |\n| [Docker](https://www.docker.com/) | Optional | Required for Shannon pentest | `brew install --cask docker` |\n| npm / yarn / pnpm | Auto-detected | Node.js dependency audit + freshness | Bundled with Node.js |\n| [pip-audit](https://pypi.org/project/pip-audit/) | Auto-detected | Python dependency audit | `pip install pip-audit` |\n| [Composer](https://getcomposer.org/) | Auto-detected | PHP dependency audit + freshness | `brew install composer` |\n| [govulncheck](https://pkg.go.dev/golang.org/x/vuln/cmd/govulncheck) | Auto-detected | Go vulnerability audit | `go install golang.org/x/vuln/cmd/govulncheck@latest` |\n| [bundle-audit](https://github.com/rubysec/bundler-audit) | Auto-detected | Ruby dependency audit | `gem install bundler-audit` |\n| [cargo-audit](https://crates.io/crates/cargo-audit) | Auto-detected | Rust dependency audit | `cargo install cargo-audit` |\n| [cargo-outdated](https://crates.io/crates/cargo-outdated) | Auto-detected | Rust outdated check | `cargo install cargo-outdated` |\n| [dotnet](https://dotnet.microsoft.com/) | Auto-detected | C#/.NET dependency audit + freshness | `brew install dotnet` |\n| [Maven](https://maven.apache.org/) | Auto-detected | Java dependency audit + freshness | `brew install maven` |\n| [Gradle](https://gradle.org/) | Auto-detected | Java dependency audit + freshness | `brew install gradle` |\n\n> **Graceful degradation:** Shield runs whatever tools are installed. Missing a tool? Shield skips that scanner and notes it in the report. Install more tools later for deeper coverage.\n\n## Installation\n\n### Automated (Recommended)\n\n```bash\ngit clone https://github.com/alissonlinneker/shield-claude-skill.git\ncd shield-claude-skill\nchmod +x install.sh\n./install.sh\n```\n\nThe install script detects your OS, installs available tools via the appropriate package manager (Homebrew on macOS, apt/pip on Linux), and validates the setup.\n\n### Manual\n\nInstall individual tools as needed:\n\n```bash\n# macOS (Homebrew)\nbrew install semgrep gitleaks trivy jq\n\n# Linux (pip + apt)\npip install semgrep pip-audit\napt install gitleaks jq # or download from GitHub releases\napt install trivy # or add Aqua Security repo\n\n# Shannon (optional -- requires Docker)\ngit clone https://github.com/KeygraphHQ/shannon.git ~/shannon\n```\n\n### Plugin Registration (Claude Code)\n\nFrom inside Claude Code, register the marketplace and install:\n\n```bash\n# Option A: From local clone\n/plugin marketplace add /path/to/shield-claude-skill\n/plugin install shield@shield-security\n\n# Option B: From GitHub\n/plugin marketplace add alissonlinneker/shield-claude-skill\n/plugin install shield@shield-security\n\n# Verify installation\n/plugin list\n```\n\nFor development and testing, load directly without installing:\n\n```bash\nclaude --plugin-dir /path/to/shield-claude-skill\n```\n\nAfter installation, the skill is available as `/shield:shield` in any project. Run `/reload-plugins` if you update the plugin files.\n\n## Usage Examples\n\n### Full Security Assessment\n\n```\n/shield:shield full\n```\n\nRuns all available scanners including Shannon pentest (requires Docker and a target URL), generates a scorecard, and produces a comprehensive markdown report with fix proposals.\n\n### Quick Scan\n\n```\n/shield:shield quick\n```\n\nRuns SAST, secrets scanning, dependency audit, and freshness check. Skips penetration testing for speed. Best for development workflow integration.\n\n### Auto-Remediation\n\n```\n/shield:shield fix\n```\n\nAnalyzes existing findings and generates before/after diffs for each vulnerability. You approve which fixes to apply, one by one or by severity tier.\n\n### Verify Fixes\n\n```\n/shield:shield verify\n```\n\nRe-runs all scanners and compares against the previous baseline. Shows new issues, resolved issues, persistent issues, and score delta.\n\n### Scorecard Only\n\n```\n/shield:shield score\n```\n\nCalculates the security risk score (0-100) from available scan data. Fast way to check posture without running a full scan.\n\n### Dependency Freshness\n\n```\n/shield:shield outdated\n```\n\nChecks all installed packages against their latest published versions. Reports MAJOR, MINOR, and PATCH version gaps.\n\n> **Note:** When installed as a standalone skill (not via plugin), use `/shield` instead of `/shield:shield`. The `:shield` namespace is only needed for plugin installations.\n\n## Configuration\n\nShield works with **zero configuration** -- it automatically detects your tech stack by scanning for lock files, config files, and source code patterns. No YAML pipelines or config files needed.\n\nFor advanced customization:\n\n| What | Where | Details |\n|------|-------|---------|\n| Custom SAST rules | `configs/semgrep-rules/*.yaml` | Add Semgrep YAML rule files per language |\n| Shannon templates | `configs/shannon-templates/*.yaml` | Pentest configuration for different app architectures |\n| Report template | `templates/report.md` | Customize the markdown report structure |\n| Issue template | `templates/issue.md` | Customize GitHub issue format |\n| SARIF template | `templates/sarif.json` | Customize SARIF export structure |\n\n### Included Shannon Templates\n\n| Template | Use Case |\n|----------|----------|\n| `web-app.yaml` | Traditional server-rendered web applications |\n| `spa-with-api.yaml` | Single-page applications with REST/GraphQL backends |\n| `api-only.yaml` | Headless API services |\n\n## Security Scorecard\n\nShield calculates a **risk score from 0 to 100** using a weighted penalty system across all findings from every scanner.\n\n### Scoring Formula\n\n```\nScore = max(0, 100 - Penalties)\n\nPenalties:\n CRITICAL findings x 15 points each\n HIGH findings x 8 points each\n MEDIUM findings x 3 points each\n LOW findings x 1 point each\n```\n\n### Risk Levels\n\n| Score Range | Risk Level | Action |\n|-------------|------------|--------|\n| 90-100 | **LOW RISK** | Minimal issues -- maintain current posture |\n| 70-89 | **MEDIUM RISK** | Minor issues -- action recommended |\n| 40-69 | **HIGH RISK** | Significant vulnerabilities -- remediation needed |\n| 0-39 | **CRITICAL RISK** | Severe exposure -- immediate action required |\n\n### Worked Examples\n\n**Project A** -- 1 CRITICAL, 5 HIGH, 2 MEDIUM findings:\n```\n100 - (1x15 + 5x8 + 2x3) = 100 - (15 + 40 + 6) = 100 - 61 = 39/100 --> CRITICAL RISK\n```\n\n**Project B** -- 0 CRITICAL, 2 HIGH, 4 MEDIUM, 3 LOW findings:\n```\n100 - (0 + 2x8 + 4x3 + 3x1) = 100 - (16 + 12 + 3) = 100 - 31 = 69/100 --> HIGH RISK\n```\n\n**Project C** -- 0 CRITICAL, 0 HIGH, 1 MEDIUM, 2 LOW findings:\n```\n100 - (0 + 0 + 1x3 + 2x1) = 100 - 5 = 95/100 --> LOW RISK\n```\n\n## Dependency Freshness\n\nBeyond vulnerability scanning, Shield checks whether your dependencies are up to date. Outdated packages are a leading vector for security incidents -- patches you never installed cannot protect you.\n\n### Version Gap Tiers\n\n| Tier | Meaning | Risk |\n|------|---------|------|\n| **MAJOR** version behind | Breaking changes between your version and latest | High -- may include security architecture changes |\n| **MINOR** version behind | New features and potential security enhancements missed | Medium -- often includes security hardening |\n| **PATCH** version behind | Bug fixes and security patches not applied | Varies -- frequently contains CVE fixes |\n\n### How It Works\n\nShield uses native package manager commands for accurate, lockfile-aware checks:\n\n| Ecosystem | Command | Output |\n|-----------|---------|--------|\n| npm | `npm outdated --json` | Current vs. wanted vs. latest for each package |\n| yarn | `yarn outdated --json` | NDJSON table with current, wanted, latest |\n| pnpm | `pnpm outdated --format json` | Same structure, workspace-aware |\n| pip | `pip list --outdated --format json` | Installed vs. latest version |\n| Composer | `composer outdated --format json` | Direct and transitive dependency status |\n| Go | `go list -m -u -json all` | Modules with available updates |\n| Ruby | `bundle outdated --parseable` | Installed vs. newest version per gem |\n| Rust | `cargo outdated --format json` | Current vs. latest per crate |\n| Maven | `mvn versions:display-dependency-updates` | Dependency version updates |\n| Gradle | `gradle dependencyUpdates -DoutputFormatter=json` | Outdated dependency report |\n| dotnet | `dotnet list package --outdated --format json` | Resolved vs. latest per NuGet package |\n\nFreshness data is included in the consolidated report and factored into remediation recommendations.\n\n## Compliance Mapping\n\nEvery finding is mapped to relevant compliance framework controls:\n\n| Framework | Coverage | Control References |\n|-----------|----------|-------------------|\n| **SOC 2** | Trust Services Criteria | CC6.1 (Logical Access), CC6.3 (Role-Based Access), CC6.7 (Data-in-Transit), CC6.8 (Input Controls), CC7.1 (System Monitoring) |\n| **PCI-DSS** | Requirements 6, 7, 11 | 6.5.x (Secure Development), 6.6 (Application Firewall), 7.1 (Access Control), 11.3 (Penetration Testing) |\n| **HIPAA** | Technical Safeguards | 164.312(a) Access Controls, 164.312(e) Transmission Security |\n\n### OWASP Top 10 Cross-Reference\n\n| OWASP 2021 | SOC 2 | PCI-DSS | Example CWEs |\n|------------|-------|---------|--------------|\n| A01 Broken Access Control | CC6.1, CC6.3 | 6.5.8, 7.1 | CWE-22, CWE-284, CWE-285, CWE-639 |\n| A02 Cryptographic Failures | CC6.1, CC6.7 | 3.4, 4.1, 6.5.3 | CWE-259, CWE-327, CWE-328 |\n| A03 Injection | CC6.1 | 6.5.1 | CWE-20, CWE-74, CWE-79, CWE-89 |\n| A04 Insecure Design | CC3.2, CC5.2 | 6.3 | CWE-209, CWE-256, CWE-501 |\n| A05 Security Misconfiguration | CC6.1, CC7.1 | 2.2, 6.5.10 | CWE-16, CWE-611 |\n| A06 Vulnerable Components | CC6.1 | 6.3.2 | CWE-1035 |\n| A07 Auth Failures | CC6.1, CC6.2 | 6.5.10, 8.1 | CWE-287, CWE-384 |\n| A08 Data Integrity Failures | CC7.2 | 6.5.8 | CWE-345, CWE-502 |\n| A09 Logging Failures | CC7.2, CC7.3 | 10.1 | CWE-117, CWE-223, CWE-778 |\n| A10 SSRF | CC6.1 | 6.5.9 | CWE-918 |\n\n## Supported Ecosystems\n\n| Ecosystem | Stack Detection | Vulnerability Audit | Outdated Check | SAST Rules |\n|-----------|:-:|:-:|:-:|:-:|\n| **Node.js** (npm/yarn/pnpm) | Yes | npm/yarn/pnpm audit | npm/yarn/pnpm outdated | 12 rules |\n| **Python** (pip/pipenv/poetry) | Yes | pip-audit | pip list --outdated | 11 rules |\n| **PHP** (Composer) | Yes | composer audit | composer outdated | 11 rules |\n| **Go** | Yes | govulncheck | go list -m -u | 10 rules |\n| **Ruby** (Bundler) | Yes | bundle-audit | bundle outdated | 10 rules |\n| **Rust** (Cargo) | Yes | cargo audit | cargo outdated | 8 rules |\n| **Java** (Maven/Gradle) | Yes | OWASP dependency-check | mvn versions / gradle dependencyUpdates | 10 rules |\n| **C#** (.NET) | Yes | dotnet list --vulnerable | dotnet list --outdated | 10 rules |\n\nStack detection, vulnerability auditing, and freshness checks work across all ecosystems listed above. Custom SAST rules are available for JavaScript/TypeScript, Python, PHP, Go, Ruby, Rust, Java, and C# (82 rules total).\n\n## Architecture\n\nShield is built as a collection of focused shell scripts, each responsible for one task. Scripts communicate via JSON on stdout, with logs on stderr.\n\n```\nscripts/\n check-prereqs.sh # Validates installed tools\n detect-stack.sh # Identifies languages, frameworks, package managers\n run-sast.sh # Runs Semgrep with language-specific rule configs\n run-secrets.sh # Runs gitleaks across git history\n run-sca.sh # Runs package manager audit (npm/pip/composer)\n run-outdated.sh # Checks for outdated dependencies with security cross-ref\n run-shannon.sh # Orchestrates Shannon pentest workflow\n generate-shannon-config.sh # Generates Shannon YAML from detected stack\n setup-shannon.sh # Initial Shannon installation helper\n consolidate.sh # Merges + deduplicates findings, assigns SHIELD IDs\n calculate-score.sh # Computes weighted risk score from findings\n generate-badge.sh # Creates shields.io badge JSON from scan results\n\nconfigs/\n semgrep-rules/ # Custom Semgrep YAML rules (JS, Python, PHP, Go, Ruby, Rust, Java, C#)\n shannon-templates/ # Pentest configs (web-app, SPA, API-only)\n\ntemplates/\n report.md # Markdown report template with Handlebars placeholders\n issue.md # GitHub issue template\n sarif.json # SARIF output template\n```\n\n### Design Principles\n\n- **Each script does one thing.** JSON in, JSON out. No hidden state.\n- **Graceful degradation.** Missing tools are skipped, not fatal. The report notes what was unavailable.\n- **Zero config by default.** Stack detection makes configuration optional for most projects.\n- **Deterministic IDs.** Findings get stable `SHIELD-XXX` identifiers for tracking across scans.\n\n## Shannon Integration\n\nShield wraps the [Shannon autonomous pentester](https://github.com/KeygraphHQ/shannon) to deliver proof-by-exploitation security testing.\n\n### What Shannon Provides\n\n- **Real attack simulation** -- not signature matching, actual exploitation attempts\n- **Proof-of-concept payloads** -- concrete `curl` commands and request bodies that demonstrate each vulnerability\n- **Attack surface mapping** -- discovers endpoints, parameters, and authentication flows automatically\n- **Workflow-based execution** -- runs multi-step attack chains, not just single-request probes\n\n### What Shield Adds on Top\n\n- **Stack-aware configuration** -- `generate-shannon-config.sh` produces Shannon YAML tuned to your detected framework (Express, Django, Laravel, etc.)\n- **Finding normalization** -- Shannon results are merged with SAST/SCA/secrets findings into unified `SHIELD-XXX` format\n- **Risk scoring** -- Shannon findings are weighted alongside other tools in the 0-100 scorecard\n- **Fix proposals** -- Shield generates code diffs to remediate issues Shannon discovered\n- **GitHub issues** -- One-click issue creation with PoC details, severity labels, and CWE tags\n\n### Requirements\n\n- Docker (running)\n- Shannon cloned locally (`git clone https://github.com/KeygraphHQ/shannon.git`)\n- Target application accessible via URL\n\n### Included Templates\n\n| Template | Target Architecture |\n|----------|-------------------|\n| `web-app.yaml` | Server-rendered apps (Express, Django, Laravel, Rails) |\n| `spa-with-api.yaml` | SPAs with REST/GraphQL backends (React+Express, Vue+FastAPI) |\n| `api-only.yaml` | Headless APIs and microservices |\n\n## Security Badge\n\nAfter scanning your project with Shield, you can add a security score badge to your README. This shows visitors that your project is actively monitored for vulnerabilities.\n\n### Generate the Badge\n\nAfter running `/shield:shield`, generate the badge file:\n\n```bash\n# From your project root (after a scan):\nbash /path/to/shield-claude-skill/scripts/generate-badge.sh /tmp/consolidated.json > shield-badge.json\n```\n\nOr ask Shield to generate it as part of the scan — it will create `shield-badge.json` in your project root.\n\n### Add to Your README\n\nCommit `shield-badge.json` to your repo, then add this to your README:\n\n```markdown\n![Shield Score](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2FYOUR_USER%2FYOUR_REPO%2Fmain%2Fshield-badge.json&query=%24.message&label=Shield%20Score&style=flat)\n```\n\nReplace `YOUR_USER` and `YOUR_REPO` with your GitHub username and repository name.\n\n### Badge Examples\n\n| Score | Badge |\n|-------|-------|\n| 100/100 | ![Shield Score](https://img.shields.io/badge/Shield_Score-100%2F100-brightgreen) |\n| 85/100 | ![Shield Score](https://img.shields.io/badge/Shield_Score-85%2F100-yellow) |\n| 55/100 | ![Shield Score](https://img.shields.io/badge/Shield_Score-55%2F100-orange) |\n| 20/100 | ![Shield Score](https://img.shields.io/badge/Shield_Score-20%2F100-red) |\n\n### Keep It Updated\n\nRe-run `/shield:shield` periodically and regenerate the badge to keep your score current. The badge reads from the JSON file in your repo, so it updates automatically when you push a new `shield-badge.json`.\n\n## Contributing\n\nContributions are welcome. Please follow this workflow:\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feat/my-feature`)\n3. Write your changes with tests\n4. Commit using [Conventional Commits](https://www.conventionalcommits.org/) (`feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`)\n5. Push to your fork and open a Pull Request\n6. Ensure tests pass\n\n### Development\n\n```bash\n# Run the test suite\nnpm test\n\n# Lint shell scripts (requires shellcheck)\nnpm run lint\n\n# Install all security tool dependencies\nnpm run install-deps\n```\n\n### Adding SAST Rules\n\nCustom Semgrep rules live in `configs/semgrep-rules/`. Each file targets one language:\n\n```\nconfigs/semgrep-rules/\n javascript.yaml # 12 rules: injection, XSS, prototype pollution, etc.\n python.yaml # 11 rules: SQLi, command injection, SSTI, etc.\n php.yaml # 11 rules: SQLi, file inclusion, deserialization, etc.\n go.yaml # 10 rules: SQLi, command injection, SSRF, insecure TLS, etc.\n ruby.yaml # 10 rules: SQLi, mass assignment, open redirect, CSRF, etc.\n rust.yaml # 8 rules: SQLi, command injection, unsafe blocks, weak random, etc.\n java.yaml # 10 rules: SQLi, command injection, XXE, deserialization, CSRF, etc.\n csharp.yaml # 10 rules: SQLi, command injection, XSS, deserialization, weak crypto, etc.\n```\n\nFollow [Semgrep's rule syntax](https://semgrep.dev/docs/writing-rules/rule-syntax/) and include `cwe`, `owasp`, and `severity` metadata in each rule.\n\n### Reporting Security Issues\n\nIf you discover a security vulnerability in Shield itself, please report it responsibly. Do **not** open a public issue. Instead, use [GitHub's Security Advisory feature](https://github.com/alissonlinneker/shield-claude-skill/security/advisories/new) to report it privately.\n\n## License\n\n[MIT](LICENSE) -- Copyright (c) 2026 ALASTecnology\n\n## Acknowledgments\n\n- **[Shannon](https://github.com/KeygraphHQ/shannon)** by KeygraphHQ -- Autonomous penetration testing engine\n- **[Semgrep](https://semgrep.dev/)** by Semgrep, Inc. -- Static analysis and pattern matching\n- **[gitleaks](https://github.com/gitleaks/gitleaks)** by Zaqueri Adams -- Secrets detection across git history\n- **[Trivy](https://trivy.dev/)** by Aqua Security -- Vulnerability scanning for containers and IaC\n", "bytes": 29419, "sha": "905abe3fa406996528e9e7de4fecdc3a2317c1f489c8ba0f4ac2e024e811d9b7", "repo_slug": "alissonlinneker/shield-claude-skill", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/plg_alissonlinneker_shield_claude_skill_shie_233ca86a/readme" }