ShadowStack v0.2

ShadowStack v0.2.0

Discovery & risk analytics for shadow-AI infrastructure.

This release adds an interactive terminal to ShadowStack — build up a scan step by step instead of assembling one long command line — along with a set of colour themes.

Highlights for v0.2.0

• New: interactive terminal (REPL) mode. Run shadowstack with no arguments (or pass -i/--interactive) to get a shadowstack> prompt: set <option> <value> to configure a scan, show to preview the resolved argv, scan/run to execute it, unset/reset to roll back, help for the full option list. The command vocabulary is generated from the same clap definitions as the one-shot CLI, so every flag is reachable and validated exactly as it is on the command line.
• New: colour themes. Six palettes for the terminal chrome — dark (default), light, matrix, ocean, amber, and mono. Set one at launch with --theme <name> or switch live inside the terminal with theme <name>. Colour auto-disables off a TTY or under NO_COLOR, and the scan report on stdout is never coloured — pipelines stay byte-clean.

Changed

• Bare invocation now opens the terminal. In 0.1, running shadowstack with zero arguments ran a one-shot MCP scan against the 127.0.0.1/32 default target. In 0.2, a bare invocation opens the interactive terminal instead. Any invocation that passes at least one flag is unaffected — existing scripted/CI usage (shadowstack --protocol mcp ..., etc.) behaves exactly as before. If you have automation that calls shadowstack with no arguments and expects a scan, add --target 127.0.0.1/32 (or your intended flags) explicitly.

Install

Download the static binary for x86-64 Linux, verify the checksum, and run:

download

curl -LO (URL) /shadowstack-0.2.0-x86_64-linux
curl -LO (URL) /shadowstack-0.2.0-x86_64-linux.sha256

verify

sha256sum -c shadowstack-0.2.0-x86_64-linux.sha256

install

chmod +x shadowstack-0.2.0-x86_64-linux
sudo mv shadowstack-0.2.0-x86_64-linux /usr/local/bin/shadowstack

shadowstack --help

The binary is statically linked (musl) — no glibc or OpenSSL required, runs on any x86-64 Linux distribution.

Quick start

Interactive terminal (new)

shadowstack
shadowstack> set protocol skills
shadowstack> set format json
shadowstack> scan

One-shot usage

shadowstack --protocol mcp --target 192.168.1.0/24
shadowstack --protocol skills --format json --output skills.json
shadowstack -p skills --fail-on high -f sarif -o results.sarif

Pick a terminal colour theme

shadowstack --theme ocean

Supported platforms

• x86-64 Linux — prebuilt static binary

Known limitations

• Discovery targets IPv4 (CIDR/host/DNS→IPv4). IPv6 ranges are not yet enumerated.
• Live MCP process inventory requires Linux /proc access

License

Apache License 2.0. See LICENSE.

ShadowStack v0.1

ShadowStack v0.1.0

Discovery & risk analytics for shadow-AI infrastructure.

First public release. ShadowStack inventories the AI-agent attack surface on your hosts — MCP servers, Claude skills & sub-agents, Cursor/Windsurf/Cline rules, and live MCP processes — scores each target, and maps every finding to MITRE ATT&CK and the OWASP LLM Top 10. Results render for a human or stream straight into a SIEM, a code-scanning dashboard, or an AI agent tasked with remediation.

It ships as a single, statically-linked binary with zero runtime dependencies — drop it on any x86-64 Linux box and run it.

Highlights

• Two scan engines in one binary:
  • --protocol mcp — network discovery of MCP servers (JSON-RPC initialize, enumerates tools/resources/prompts, captures TLS + HTTP banners) across CIDRs, hosts, and DNS names.
  • --protocol skills — filesystem audit of Claude skills, sub-agents, slash commands, CLAUDE.md/AGENTS.md, Cursor/Windsurf/Cline rules, MCP client configs and hooks — plus a live /proc inventory of running stdio MCP servers (Linux).
• Severity + risk scoring — every finding is High/Medium/Low; targets are ranked by a weighted score (10·H + 4·M + 1·L) into none/low/medium/high/critical bands.
• MITRE ATT&CK / OWASP LLM Top 10 (2025) mapping + remediation guidance on every finding, carried through all output formats.
• Five output formats — ascii (human), json (full inventory + risk + findings), and findings-only ndjson (SIEM), sarif 2.1.0 (GitHub code-scanning), and csv (triage).
• Stable finding identity — derived rule IDs (SS-MCP-… / SS-SKL-…) and dedup fingerprints enable diffing across scans.
• Built for recurring/automated use — baseline/delta mode, CI exit gating, allow-list suppression, version-controllable scan profiles, resumable sweeps, and pipe-safe stdout/stderr separation.

Features

Discovery

• MCP over both Streamable-HTTP and SSE transports; protocol-version negotiation (2025-06-18 → 2024-11-05).
• HTTP and TLS (TLS captured as evidence — self-signed/expired/internal certs become findings, not connection errors).
• GET /.well-known/mcp discovery docs; 401+WWW-Authenticate: Bearer hosts surfaced as suspected (auth-gated) MCP servers.
• Flexible targeting: repeatable/comma-separated --target (alias --cidr) taking any mix of CIDRs, IPv4s, and DNS names; --targets-file scope lists; merged + de-duplicated.
• Live process inventory (Linux /proc): npx @modelcontextprotocol/*, uvx/pipx/bunx runners, python -m mcp_server_*, mcp-server/mcp-proxy binaries, node/bun/deno scripts.

Rules & analytics

• MCP rules: transport, TLS, auth/Origin, identity, capabilities, instructions, tools, resources/templates, prompts, banners, suspected auth-gated hosts, and multi-signal correlations (rug-pull, exfil/RCE chains, cross-server tool shadowing).
• Skills rules: file metadata, frontmatter, tool-grant/auto-approve directives, content (URLs/IPs/scripts/commands/keywords), concealment detection (zero-width/bidi/Unicode-tag/ANSI/base64), hooks, MCP config, live process, and generic/linux/windows TTP correlations.
• Per-target weighted risk ranking shared by the ASCII and JSON renderers.

Operations

• --baseline <prior-report> — emit only findings new since a prior scan (format-agnostic).
• --fail-on <high|medium|low> — exit code 2 for CI/CD gating.
• --allow-list <file> — suppress accepted findings (category/target globs); suppressed count still reported.
• --config <profile.toml> — pin flags into a version-controllable profile (CLI flag > profile > default).
• --resume <file> — restartable, identity-pinned CIDR sweeps (MCP).
• --max-duration / --per-host-delay / --connect-retries / --connect-backoff — politeness & resilience knobs.
• -v/-q leveled logging to stderr; report stays clean on stdout.

Install

Download the static binary for x86-64 Linux, verify the checksum, and run:

# download (replace <tag-url> with this release's asset URL)
curl -LO <tag-url>/shadowstack-0.1.0-x86_64-linux
curl -LO <tag-url>/shadowstack-0.1.0-x86_64-linux.sha256

# verify
sha256sum -c shadowstack-0.1.0-x86_64-linux.sha256

# install
chmod +x shadowstack-0.1.0-x86_64-linux
sudo mv shadowstack-0.1.0-x86_64-linux /usr/local/bin/shadowstack

shadowstack --help

The binary is statically linked (musl) — no glibc or OpenSSL required, runs on any x86-64 Linux distribution.

Quick start

# Discover MCP servers on a /24
shadowstack --protocol mcp --target 192.168.1.0/24

# Audit the local AI surface as JSON
shadowstack --protocol skills --format json --output skills.json

# CI gate: fail on any High finding, emit SARIF for code-scanning
shadowstack -p skills --fail-on high -f sarif -o results.sarif

Supported platforms

• x86-64 Linux — prebuilt static binary (this release).
• The live process inventory (/proc) is Linux-only; all other functionality is portable and the codebase builds on other targets from source.

Known limitations

• Discovery targets IPv4 (CIDR/host/DNS→IPv4). IPv6 ranges are not yet enumerated.
• Live MCP process inventory requires Linux /proc; on other OSes the process list is empty (the rest of the scan is unaffected).

License

Apache License 2.0. See LICENSE.