Sigil

---

Sigil scans repositories, packages, MCP servers, skills, and agent tooling for malicious patterns before they reach your working environment. Nothing is installed or run before it has been scanned and scored, and you decide what to approve. That includes the package tools Sigil calls: sigil pip downloads only the prebuilt wheel of the release pip install would pick, and sigil npm downloads the registry tarball itself and checks it against the registry's integrity; both refuse paths, URLs and git specs, which pip or npm would build or run scripts for (--allow-build-scripts accepts them for code you already trust, after you confirm at a terminal, and with a warning). Up to 1.3.7, sigil pip let pip run a source distribution's setup.py, and sigil npm of a local directory or git spec let npm pack run its lifecycle scripts, before the scan.

The AI tooling ecosystem moves fast. Developers clone repos from tutorials, install MCP servers with 12 GitHub stars, and pull agent skills from Discord — all of which get direct access to API keys, databases, and cloud credentials. Traditional dependency scanners catch known CVEs but miss the real threat: intentionally malicious code designed to exfiltrate credentials, establish backdoors, or execute arbitrary commands via install hooks.

Sigil fills this gap with a quarantine-first approach.

Quick Install

Install via Script:

# Clone the repository
git clone https://github.com/NOMARJ/sigil.git
cd sigil

# Run the installer — downloads the prebuilt release binary for your
# platform and wires up the Claude Code integration by default
# (opt out with --no-integrations)
./install.sh

# Optional: add gclone/safepip/safenpm shell aliases
./install.sh --with-aliases

Package managers:

# Homebrew (macOS/Linux)
brew install nomarj/tap/sigil

# npm (macOS/Linux)
npm install -g @nomarj/sigil

# Cargo (Rust)
cargo install sigil-cli

# curl installer
curl -fsSLO https://www.sigilsec.ai/install.sh && sh install.sh

Coming Soon:

• Docker: docker pull nomark/sigil:<version> (images will carry only version tags, no latest; see installation)

Note: The sigil package name on crates.io is occupied by an unrelated project. Install the Rust CLI with cargo install sigil-cli.

→ See all installation methods

How It Works

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  You run a   │────▶│  Sigil       │────▶│  Clean?      │
│  command     │     │  quarantines │     │  Approve.    │
│              │     │  & scans     │     │  Dirty?      │
│  gclone      │     │              │     │  Reject.     │
│  safepip     │     │  8 phases.   │     │              │
│  safenpm     │     │  <3 seconds. │     │  You decide. │
└──────────────┘     └──────────────┘     └──────────────┘

Sigil runs eight analysis phases on every scan (all free; LLM analysis requires Pro):

Phase	What It Catches	Tier
Install Hooks	setup.py cmdclass, npm postinstall, Makefile targets that execute on install	Free
Code Patterns	eval(), exec(), pickle.loads, child_process, dynamic imports	Free
Network / Exfil	Outbound HTTP, webhooks, socket connections, DNS tunnelling	Free
Credentials	ENV var access, .aws, .kube, SSH keys, API key patterns	Free
Obfuscation	Base64 decode, charCode, hex encoding, minified payloads	Free
Provenance	Git history depth, author count, binary files, hidden files	Free
Prompt Injection	AI agent instruction injection in code, docs, and tool descriptions	Free
Skill Security	MCP permission escalation, over-broad agent tool grants	Free
🔒 LLM Analysis	AI-powered zero-day detection, contextual threat correlation, advanced remediation	Pro

Each finding is weighted and scored. You get a clear verdict:

Evidence (details)	Verdict	What Happens
Nothing that reaches MEDIUM (typically no findings, or Low-severity observations only)	LOW RISK	No known malicious patterns detected
A Medium-or-above finding in the code itself, a High or Critical one anywhere (tests included), or 10+ points of Medium-and-above findings	MEDIUM RISK	Suspicious patterns — review before approving
HIGH gate: a High or Critical finding in the code itself that is a real part of the package	HIGH RISK	Dangerous patterns — review carefully before use
Critical evidence	CRITICAL RISK	Strong malicious indicators — regardless of score

The verdict follows the evidence, not the printed score: Low observations never raise it, a pile of Medium findings stops at MEDIUM RISK, and HIGH needs a High or Critical finding in the code the package runs. CRITICAL is evidence-gated: it needs one Critical finding from a rule whose evidence stands alone, or Critical findings from two different rules that are individually inconclusive (a private key in a test fixture, for instance).

Every scan also prints a letter grade (A–F, a label over the verdict), the behaviours the findings add up to (exfiltration, persistence, harvests_credentials, …), the five key risks, and what it scanned (npm, pypi, agent-skill, mcp-server, …). Findings carry remediation text and references; a reviewed finding can be silenced in place with # sigil:ignore RULE-ID -- reason and stays in the report as suppressed.

Usage

Core Commands

# Clone a repo into quarantine, scan it, get a verdict
sigil clone https://github.com/someone/cool-mcp-server

# Download and scan a pip package before installing (prebuilt wheels only:
# no package code runs before the scan)
sigil pip some-agent-toolkit

# Download and scan an npm package before installing (the registry
# tarball, checked against the registry's integrity; no package code runs)
sigil npm langchain-community-plugin

# Scan a directory or file already on disk — or a git URL (quarantined first)
sigil scan ./downloaded-skill/
sigil scan https://github.com/someone/cool-mcp-server
sigil scan ./downloaded-skill/ --format html > report.html   # shareable report
sigil scan ./downloaded-skill/ --format json | jq .summary    # verdict, score, grade, platform

# What installed agent tooling left behind on THIS machine (read-only, then reversible)
sigil residue scan        # shell rc edits, cron/launchd/systemd, git hooks, credential modes, /etc/hosts
sigil residue plan        # the fixes it would make, without making them
sigil residue apply       # apply with a backup of every target; undo with `sigil residue rollback --last`

# 🔒 Pro: Enhanced LLM-powered scanning (requires authentication)
sigil login                               # browser-based device authorization
sigil scan ./code --enhanced              # AI-powered threat detection
sigil scan ./code --enhanced --verbose    # With detailed output
# (cloud options run only on a fresh scan: add --no-cache if ./code, or a copy of it, was scanned before)

# Download and scan any URL: archives, single files, GitHub /tree/ links
sigil scan https://example.com/agent-tool.tar.gz

# Manage quarantine
sigil list              # See all quarantined items
sigil approve abc123    # Mark trusted: pins the item's digest in the trust ledger
                        # (files stay at ~/.sigil/quarantine/<id>/ — copy them out yourself)
sigil reject abc123     # Permanently delete quarantined code

# Wire Sigil into your tooling
sigil setup claude      # Register the Claude Code plugin (marketplace + install)
sigil setup shell       # Add gclone/safepip/safenpm aliases to your shell rc
sigil setup git         # Install a pre-commit hook (sigil scan --fail-on high)
sigil setup all         # claude + shell, plus git when run from a repository's root

Shell Aliases

Aliases are opt-in: run ./install.sh --with-aliases (or sigil setup shell) to append them to your shell rc. Use the commands you already know — Sigil protects you automatically:

Alias	What It Does
gclone <url>	git clone with quarantine + scan
safepip <pkg>	sigil pip: download into quarantine and scan (does not install)
safenpm <pkg>	sigil npm: download into quarantine and scan (does not install)

Add others yourself if you want them, for example alias audithere='sigil scan .' and alias qls='sigil list'.

IDE & Agent Integrations

Sigil works where you work. Install the plugin for your editor, or connect AI agents via MCP:

Integration	Coverage	Install
VS Code / Cursor / Windsurf	Scan workspace, files, selections, packages. Findings in Problems panel.	plugins/vscode
JetBrains IDEs	IntelliJ, WebStorm, PyCharm, GoLand, CLion, etc. Tool window + inline annotations.	plugins/jetbrains
Claude Code Plugin	6 skills + 2 security agents. Blocks unscanned installs/clones by default.	plugins/claude-code
Claude Code (MCP)	9 tools: scan, scan_package, clone, quarantine, approve, reject, check_package, search_database, report_threat.	plugins/mcp-server
GitHub Actions	Run Sigil as a CI check on every PR.	action.yml

Claude Code Plugin (Recommended)

Install as a native Claude Code plugin — enforcement, skills, agents, and the MCP server in one step:

# Add Sigil marketplace
claude plugin marketplace add NOMARJ/sigil

# Install the plugin
claude plugin install sigil-security@sigil-marketplace

This provides:

• Enforcement by default - a PreToolUse hook blocks git clone, npm install <pkg>, and pip install <pkg> in Claude Code sessions, redirecting them through Sigil's quarantine (bypass per-command with SIGIL_BYPASS=1, tune with SIGIL_GUARD_MODE=enforce|advise|off)
• Bundled MCP server - registered automatically, no separate config
• /sigil-security:scan-repo - Scan repositories
• /sigil-security:scan-package - Audit npm/pip packages
• /sigil-security:scan-file - Analyze specific files
• /sigil-security:review-quarantine - Manage findings
• /sigil-security:fix-finding - Propose fixes for scan findings
• /sigil-security:generate-policy - Generate sandbox policies from scan results
• @security-auditor - Expert threat analysis agent
• @quarantine-manager - Quarantine workflow agent

→ See Claude Code plugin documentation

MCP Server (Other Agents)

Any MCP-compatible client (Cursor, Windsurf, custom agents) can use Sigil's tools directly:

{
  "mcpServers": {
    "sigil": {
      "command": "npx",
      "args": ["-y", "@nomark/sigil-mcp-server"]
    }
  }
}

Note: @nomark/sigil-mcp-server v1.3.0 is not yet published to npm — the npx config above will work once it is. Until then, build from source (cd plugins/mcp-server && npm install && npm run build) and point your MCP client at node /path/to/sigil/plugins/mcp-server/dist/index.js.

→ See MCP integration guide

Threat Intelligence

Sigil can connect to a community-powered threat intelligence database, on request and with a Pro plan: sigil scan --enrich looks the scanned directory's hash up in it, and sigil fetch downloads its threat signatures, which later fresh scans apply (content scanned before the fetch, in that directory or a copy of it, is re-checked only after sigil clear-cache or with --no-cache). The database is keyed by the hash of a package artifact, while --enrich sends a hash of the directory's file paths and sizes, so it matches only an entry recorded for that exact directory: no match does not mean the code is safe. Logging in (sigil login) stores the token these send; it does not change a plain scan. sigil scan --submit sends a scan's findings to the Sigil API for your scan history (see below for what that includes). CLI 1.3.7 prints results submitted to Sigil cloud and an --enrich match to stdout after the report, so with -f json or -f sarif its stdout is no longer a valid report: write the report with -o FILE, or upgrade the CLI, which writes these messages to stderr. Which of these requests an API accepts depends on its version (API update rollout). An --enrich match is for information only: it does not change the verdict, the exit code or the -f report. New signatures reach your CLI only when you run sigil fetch; nothing is synced automatically.

What gets transmitted depends on how you use Sigil — see docs/data-handling.md for the exact per-tier breakdown:

• Default (logged in or not): no source code, no account needed. All eight phases run locally. When a scanned directory has a requirements.txt, package-lock.json, Cargo.lock or go.mod, sigil scan looks the listed dependencies up in OSV (and npm/PyPI packages on their registry), which sends their names and versions; for advisories numbered CVE-… it also downloads the CISA KEV catalogue and sends those CVE IDs to FIRST's EPSS API.
• Scan submission (sigil scan --submit, after sigil login): submissions include finding metadata (rule IDs, severities, file paths) and the flagged source lines (the code excerpts shown in your scan output). Full files are not uploaded.
• AI explanation (sigil explain scan.json, after sigil login): every finding in that saved report, flagged source lines included, goes to the Sigil API, which has an LLM provider adjudicate one of them.
• Pro AI investigation: source files are uploaded and shared with an LLM provider to produce the analysis (sigil scan --enhanced uploads up to 50 eligible text files under the target directory, collected independently of scan exclusions, plus the scan result: every finding with its flagged source line, including findings in files outside those 50). This is what you are paying for — the AI reads your code. Never enable Pro analysis on code you cannot share. The API does not yet return LLM findings for --enhanced: it stores the scan and answers with its static analysis, and the CLI says so (CLI 1.3.7 prints Enhanced analysis failed and keeps its static results). The API keeps the uploaded files out of the stored scan; an API without the update stores them with the scan record, where the account and its team can read them (see API update rollout and Data Handling).

Offline mode: All eight scan phases run locally without authentication. Threat intelligence lookups are skipped, but you still get full local analysis.

# Authenticate, then use threat intel explicitly (Pro plan)
sigil login
sigil fetch                       # download threat signatures
sigil scan . --enrich --no-cache  # hash lookup in the threat database

The cloud options of sigil scan (--enrich, --submit, --enhanced) run only on a fresh scan: a re-scan that reuses a cached result skips them with a warning on stderr, hence --no-cache. For a repository URL, sigil scan runs the sigil clone workflow, which ignores them (and --fail-on) without a message.

Learn more about authentication →

Why Not [Existing Tool]?

Capability	Sigil	Aardvark/Codex	Claude Code	Snyk	Semgrep	Prism Scanner
Pre-install quarantine	✅	❌	❌	❌	❌	❌
Host residue cleanup	✅ Reversible	❌	❌	❌	❌	✅
Supply-chain attacks	✅ Primary	⚠️ Limited	⚠️ Limited	⚠️ CVEs	❌	⚠️ Patterns
Install hook scanning	✅	❌	❌	❌	❌	⚠️ package.json scripts
Malware analysis	⚠️ Patterns	✅ Dedicated	⚠️ Context	❌	❌	⚠️ Patterns
AI-powered analysis	❌	✅ GPT-5	✅ Claude	⚠️ Limited	❌	❌
Deep vuln scanning	⚠️ Patterns	✅ 92% recall	✅ Primary	✅	✅	❌
Auto-patching	❌	✅ Codex	✅ AI patches	⚠️ Limited	❌	❌
AI agent / MCP focus	✅	✅	✅	❌	❌	✅ Skills / MCP
Multi-ecosystem	✅ All	✅	✅	✅	✅	⚠️ Python AST; regex elsewhere
Free tier	✅ Full	Private beta	Waitlist	Limited	OSS	✅ Apache-2.0

Sigil vs NVIDIA SkillSpector — measured

Both tools on the same real samples, static analysis on both sides. Full method, the cases Sigil loses, and the feature comparison: docs/comparison/skillspector.md.

Data Source: Real samples. Malicious: Datadog malicious-software-packages-dataset, ai-skills bucket.
             Clean: every skill in anthropics/skills, NVIDIA/skills, openai/skills,
             vercel-labs/agent-skills; 169 MCP servers from the official MCP registry.
Sample Size: 204 malicious skills, 455 clean skills, 169 clean MCP servers.
Limitations: SkillSpector 2.11.2 with --no-llm (its optional LLM stage was not measured).
             "Clean" is vendor-published, not audited. Sigil's newer rules were written after
             reading these corpora, so its figures are in-sample.

	Malicious blocked	Clean skills blocked	Clean skills warned
Sigil	173/204 (84.8%)	7/455 (1.5%)	71/455 (15.6%)
SkillSpector 2.11.2	45/203 (22.2%)	118/455 (25.9%)	282/455 (62.0%)

Clean MCP servers	Blocked	Warned
Sigil	29/169 (17.2%)	95/169 (56.2%)
SkillSpector 2.11.2	100/156 (64.1%), 13 timed out	127/156 (81.4%)

Sigil's MCP row is from the build that reports credential values whatever their shape and whose npm lifecycle-script rewrites fail closed (28 and 89 with the withdrawn credential exemptions; 24 and 76 before the rewrites failed closed; 39 and 125 before the third false-positive pass); SkillSpector was not re-run for it. See docs/detection/mcp-server-calibration.md.

Median scan time per skill, both tools in one run on the same machine: 1.38 s for Sigil (before this change) and 26.82 s for SkillSpector; the current build measured 1.48 s in its own run. SkillSpector can send findings to a model you choose for adjudication; Sigil's LLM analysis runs on Sigil's service.

The Complete Stack:

• Sigil (Layer 1): Quarantine-first before code enters your environment (supply-chain protection)
• Aardvark/Codex Security (Layer 2): Deep AI analysis after code is committed (GPT-5 powered)
• Claude Code Security (Layer 2): Deep AI analysis after code is committed (Claude powered)

Positioning:

• Aardvark and Claude Code Security compete (both do deep vulnerability scanning)
• Sigil complements both (different layer: pre-install vs post-commit)
• Use Sigil + (Aardvark OR Claude Code Security) for complete coverage

→ See complete integration guide

Snyk and Dependabot flag known CVEs — they don't scan for intentional malice. Socket.dev is npm-only. Semgrep is a pattern engine, not a workflow. The AI security stack (Sigil + Aardvark/Claude Code Security) provides defense-in-depth.

Detection Accuracy — Measured, Not Marketed

Sigil publishes its measured detection numbers, including the ones that aren't flattering. Full method and results for this release: evaluation_results/honest_detection_eval.md (recall and the clean control set) and evaluation_results/honest_detection_eval_control_verdicts.json (each clean package's verdict); every run is in evaluation_results/HISTORY.md.

Data Source: Datadog malicious-software-packages-dataset (real, human-triaged
             malicious npm/PyPI packages) + a 20-package clean control set of
             popular npm/PyPI packages fetched from the live registries.
Sample Size: 844 malicious samples (204 per ecosystem/category bucket, including
             the dataset's AI-skills bucket); 20 clean control packages.
Limitations: Dataset has GuardDog selection bias (Datadog's own disclaimer).
             Offline static phases only. Small clean control set. The clean-set
             row counts a package as flagged if it contains one finding at that
             severity, which is a stricter reading than the verdict a CI gate
             sees — both are given below.

Metric	v1.3.7 (this release)	Previous run with a control set (da316a5)
Recall (malicious detected, any severity)	93.01% (785/844)	91.47%
Recall at ≥ Medium	90.17% (761/844)	90.52%
Recall at ≥ High	89.10% (752/844)	85.07%
Recall at ≥ Critical	66.35% (560/844)	65.52%
Clean packages with a ≥ High finding, first scan	55% (11 of 20)	65% (13 of 20)
Clean packages returning a CRITICAL RISK verdict	2 of 20 (vite, boto3)	0 of 20
Clean packages returning HIGH RISK or worse	7 of 20	16 of 20
FP rate after trust-ledger approval (sigil approve)	not re-measured	0%
FP rate at ≥ High with Pro AI adjudication	not re-measured	not re-measured (30% two runs earlier)

Recall compares directly: the malicious samples are the same 844 in both columns, and the release run's recall equals the run that measured the same code before release (dataset commit 1dbcfc5, fingerprint 63fcde5b…) at every threshold. The clean columns do not compare like for like. The control set was fetched again from the live registries for this release, so its package versions (and possibly some names) differ from the earlier set, which was not recorded. Read them as two measurements, not a trend. Two clean packages now return CRITICAL RISK, which the earlier run did not: vite (CODE-001/002/008/014, OBFUSC-012, SUPPLY-001/008/014) and boto3 (CRED-004, SUPPLY-003). Beyond packages, the release's false-positive measurements on agent skills and MCP servers: 7 of 455 clean vendor skills blocked (1.5%, down from 108) and 29 of 169 clean MCP servers blocked (39 before the third false-positive pass). See docs/comparison/skillspector.md and docs/detection/mcp-server-calibration.md.

The AI-skills bucket was the weakest by a wide margin and is no longer: on the 60-sample subset the harness reports it at 95.0% detected at any severity and 90.0% at ≥ High, against 68.3% and 48.3% before. Some of that gap was never real — a rule was matching the word "exec" in English prose, so it scored markdown headings like ### Code Execution as Critical. Removing it lowers the old number and raises the new one; see docs/research/prism-scanner-lessons.md.

What this means in practice: the static phases deliberately over-trigger — network calls, base64, and env access are dangerous in malware and routine in legitimate code, and a first scan of a normal package will often come back MEDIUM or HIGH. That is the designed workflow, not a bug: review the findings, then sigil approve what you trust (drops its findings to zero on re-scan) or use Pro's false-positive verification to have AI adjudicate them. Recall is unaffected by ledger approvals (measured recall_delta = 0).

Grade badge

Every scan carries a letter grade in --format json (summary.grade) and in the GitHub Action's grade / badge outputs. The grade is derived from the verdict — scoring is unchanged, this is just a shorter label for it:

Grade	Verdict	Badge
A	No findings
B	Low-severity observations only
C	MEDIUM RISK
D	HIGH RISK
F	CRITICAL RISK

Badge markdown, ready to paste (swap the letter and colour for your grade):

[![Sigil grade A](https://img.shields.io/badge/Sigil-Grade%20A-brightgreen?style=flat-square)](https://github.com/NOMARJ/sigil)
[![Sigil grade B](https://img.shields.io/badge/Sigil-Grade%20B-green?style=flat-square)](https://github.com/NOMARJ/sigil)
[![Sigil grade C](https://img.shields.io/badge/Sigil-Grade%20C-yellow?style=flat-square)](https://github.com/NOMARJ/sigil)
[![Sigil grade D](https://img.shields.io/badge/Sigil-Grade%20D-orange?style=flat-square)](https://github.com/NOMARJ/sigil)
[![Sigil grade F](https://img.shields.io/badge/Sigil-Grade%20F-red?style=flat-square)](https://github.com/NOMARJ/sigil)

The GitHub Action emits the same markdown as its badge output and prints it in the job summary.

A badge is a point-in-time static-analysis result for the commit that was scanned. It is not a certification, and it says nothing about code added after the scan.

Pricing

The CLI is free and open source with all eight scan phases. Sigil Pro turns your scanner into an AI security consultant.

	Open Source	Pro — $29/mo	Team — $99/mo
Full CLI scanning	✅	✅	✅
🤖 AI Finding Investigation	—	✅	✅
🔍 False Positive Verification	—	✅	✅
💬 Interactive Security Chat	—	✅	✅
⚡ Smart Model Routing	—	✅	✅
Monthly AI credits	—	5,000	50,000
Monthly cloud scans	—	500	5,000
Cloud threat intelligence	—	✅	✅
Scan history	—	90 days	1 year
Web dashboard	—	✅	✅
Team management & policies	—	—	Up to 25 seats
CI/CD integration	—	—	✅
Slack / webhook alerts	—	—	✅

Why upgrade? Transform cryptic security alerts into actionable intelligence. Instead of wondering "Is this real?", get AI-powered explanations, threat assessments, and verification in seconds.

See full pricing →

Documentation

Comprehensive documentation is available in the docs/ directory:

Getting Started:

• Getting Started Guide — Installation and first scan
• CLI Reference — All commands and options
• Authentication Guide — Connect to Sigil Pro
• Configuration — Environment variables and settings

Technical Deep Dives:

• Architecture Overview — System design
• Detection Patterns — What Sigil scans for
• Threat Intelligence 2025 — Current threat landscape
• API Reference — REST API endpoints

Integration Guides:

• CI/CD Integration — GitHub Actions, GitLab CI, etc.
• IDE Plugins — VS Code, JetBrains setup
• MCP Server — Use Sigil as an MCP tool for AI agents
• AI Security Stack — Sigil + Aardvark + Claude Code Security
• Claude Code Security Integration — Defense-in-depth with Anthropic
• AI Agent Integration — Claude Code, MCP, and other AI agents

Security Research:

• Case Study: OpenClaw Attack — Real-world supply chain attack
• Prompt Injection Patterns — Detection techniques
• Malicious Signatures — Threat signature database

Browse all documentation →

Roadmap

See ROADMAP.md for the full roadmap.

Today: Quarantine-first scanning for pip, npm, and git repos. Eight-phase behavioral detection. Custom scan rules in YAML or JSON. Dependency advisory lookups for requirements.txt, package-lock.json, Cargo.lock and go.mod. Cloud threat intelligence with community reporting and signature sync. Dashboard with scan history, team management, and policy controls. Rust CLI binary, VS Code / Cursor / Windsurf extension (.vsix), JetBrains plugin, MCP server for AI agents, and GitHub Actions integration.

Now: Hosted cloud — sign up and scan without running infrastructure.

Next: Docker image. VS Code Marketplace and JetBrains Marketplace listings. Enterprise SSO, RBAC, and audit logs. GitLab, Jenkins, and CircleCI integrations.

Contributing

We welcome contributions. See CONTRIBUTING.md for guidelines.

Security

Found a vulnerability? Please report it responsibly. See SECURITY.md.

License

Apache 2.0 — see LICENSE for details.

---