Skip to content

README.md

Latest commit

 

History

History
177 lines (129 loc) · 7.42 KB

README.md

File metadata and controls

177 lines (129 loc) · 7.42 KB
Raw

ShadowMap

ShadowMap logo

ShadowMap is a Rust framework for disciplined subdomain enumeration, vulnerability detection, and attack-surface mapping at scale.

Key Features

  • Comprehensive discovery: Aggregates subdomains from CRT.sh and complementary sources with IDN normalization and wildcard handling.
  • Built-in validation: Resolves DNS, inspects headers and TLS, and flags CORS or takeover risks with heuristic de-duplication.
  • Performance-first engine: Async Rust core with configurable concurrency to cover large scopes quickly.
  • Actionable exports: Ships clean CSV, JSON, and TXT outputs for reporting or downstream automation.
  • Extensible recon modules: Plug-in architecture for port scanning, fingerprinting, and cloud exposure checks.
  • Rig-style autonomy: Optional agent orchestrator that sequences every recon module, retries failures, and flags deep cloud assets automatically.

Getting Started

Prerequisites

  • Rust 1.70 or newer (includes Cargo)

Build & Install

git clone https://github.com/YOUR-ORG/ShadowMap.git
cd ShadowMap
cargo build --release

First Scan

./target/release/shadowmap -d example.com -o results.csv

Quality Checks

cargo fmt --all
cargo clippy --workspace --all-targets -- -D warnings

Supply Chain Security

ShadowMap includes a lightweight workflow for generating a Software Bill of Materials (SBOM) and scanning it for known vulnerab ilities. The steps below follow the cargo-cyclonedx + Grype quickstart from the securi ty guide referenced in this task.

  1. Install cargo-cyclonedx (once per machine):

    cargo install cargo-cyclonedx

  2. Install Grype (Linux/WSL example):

    curl -sSfL https://raw.githubusercontent.com/anchore/grype/main/install.sh | sudo sh -s -- -b /usr/local/bin

    Refer to the Grype README for macOS and Windows alternatives.

  3. Generate the SBOM in CycloneDX JSON format with all ShadowMap features enabled. Overriding the filename causes cargo-cyclonedx to place the SBOM in the current working directory, making it easy to move or archive:

    cargo cyclonedx --format json --spec-version 1.5 --all-features --override-filename bom
# cargo-cyclonedx writes bom.json into the current working directory; move it if you prefer a different location

  4. Scan the SBOM with Grype (pointing at whichever location you chose above):

    grype sbom:./bom.json

  5. (Optional) Export detailed findings:

    grype sbom:./bom.json -o json --file vulnerability-report.json

For repeatability you can run ./scripts/security-scan.sh which wraps the SBOM generation and Grype scan with sensible defaults.

Data Security & Compliance

ShadowMap aligns its operational safeguards with SOC 2 Trust Services Criteria and GDPR privacy requirements. The Data Security and Compliance Strategy describes the control owners, evidence expectations, and validation activities that keep reconnaissance data secure throughout its lifecycle.

Technical report automation

Run ./scripts/generate-technical-report.sh to materialize the latest reconnaissance brief as build/technical-report.md. The Generate technical report PDF workflow wires this script into the CI pipeline and uses Pandoc to emit a downloadable artifact—trigger it manually from the Actions tab whenever you need a fresh PDF without committing binaries.

Application Governance & Resilience

Teams that need to spot unapproved apps, fragmented data flows, or silent system failures can extend ShadowMap's discoveries into governance and reliability workflows using the Application Governance Integration guide. It outlines how to fuse ShadowMap outputs with CMDBs, data lineage tools, and observability platforms to close monitoring gaps.

Organizational Adoption Playbook

Security programs that want to operationalize ShadowMap across large enterprises can follow the Organizational Adoption Playbook. It lays out governance structures, stakeholder roles, and business metrics that translate reconnaissance coverage into measurable risk reduction and executive-aligned value.

Automated security workflow

The repository ships with a dedicated GitHub Action located at .github/workflows/security-scan.yml. It installs cargo-cyclonedx and grype, generates shadowmap-bom.json, scans it for vulnerabilities, and uploads the SBOM plus a JSON report as build artifacts. The workflow runs automatically for pull requests and pushes to main, and can also be started manually from the Actions tab via the Run workflow button.

Desktop GUI (optional)

cargo run --features gui --bin shadowmap-gui

Enter a target domain in the GUI and select Run Scan; results are written to the output directory displayed on completion. The interface is implemented entirely in Rust via iced.

Usage

Run a default reconnaissance scan and export CSV output:

shadowmap -d example.com -o results.csv

Adjust concurrency to tune throughput for large scopes:

shadowmap -d example.com -c 50 -o results.json

Pipe JSON output for downstream automation:

shadowmap -d target.com --json > report.json

Enable the autonomous Rig-inspired orchestrator with deep cloud discovery:

shadowmap -d target.com --autonomous

The agent executes each reconnaissance stage with retry-aware control flow, surfaces SaaS predictors, and produces cloud_assets.json alongside traditional reports for deep storage/bucket exposure review.

Output

subdomain,http_status,server_header,open_ports,cors_issues,fingerprints,takeover_risks
api.example.com,200,nginx,"80,443","Wildcard CORS allowed","{server: nginx, framework: react}","None"
cdn.example.com,0,,,"","",Potential AWS S3 takeover

Roadmap

  • Passive and active DNS integrations (SecurityTrails, Shodan, etc.)
  • Advanced port fingerprinting through Nmap integration
  • Plugin system for bespoke reconnaissance modules
  • Cloud asset exposure detection (GCP Buckets, Azure Blobs, etc.)
  • Continuous recon mode for persistent monitoring

Acknowledgements

ShadowMap's SBOM generation and vulnerability scanning workflows rely on the CycloneDX standard and the Grype scanner maintained by Anchore. If you redistribute ShadowMap guidance or reuse the automation scripts, please keep those upstream attributions (or submodule references) intact so the maintainers receive credit for their work.

Disclaimer

This tool is for educational and authorized security testing only. Do not use ShadowMap against systems you don’t own or have explicit permission to test.

Contributing

Pull requests are welcome! Please open an issue to discuss improvements, new modules, or bug fixes.

Project Principles

ShadowMap is built on the idea that defenders need fast, global, reliable, and open tooling to match adversary velocity.

Contributions

Alt