WraithWall

Deception-and-threat-intelligence platform. Honeypots, attacker identity, MITRE ATT&CK mapping, incident-response playbooks, active-defense gateway and a public intelligence API — deployed as one Flask application you run yourself.

WraithWall takes hostile traffic at the perimeter (SSH/SHTTP honeypots, canary tokens, lures), turns it into scored, correlated intelligence (behavioural fingerprinting, campaign clustering, ATT&CK technique mapping), and hands an operator the response (playbooks, deception deployment, immutable audit trail). Everything is self-hosted: no SaaS dependency, no telemetry leaves your host.

• Live deployment: https://wraithwall.online
• Source: https://github.com/niffyhunt/wraithwall
• PyPI: pip install wraithwall

What is in this package

pip install wraithwall installs the platform as a library and a CLI:

Entry points: create_app() (application factory), Client (API client), wraithwall (CLI).

Quick start

pip install wraithwall
wraithwall check          # routes + blueprints sanity check
wraithwall serve          # gunicorn-backed server on :8000

From source:

git clone https://github.com/niffyhunt/wraithwall.git
cd wraithwall
./install.sh
cp .env.example .env
docker compose up -d
wraithwall check
wraithwall serve

Ecosystem

Packages are independent — none imports another.

Python API

from wraithwall import create_app, Client
from wraithwall.link_checker import analyze
from wraithwall.gateway import Gateway

app = create_app()
client = Client("http://localhost:8000", api_key="...")
print(client.health())
result = analyze("https://example.com")
blocked = Gateway.is_ip_blocked("203.0.113.1")

from ravenscan import scan
from canary_kit import create_canary

profile = scan(".")
token = create_canary("my-sdk", "1.0.0")

CLI

wraithwall check                 # validate routes and blueprints
wraithwall serve --port 8000     # run the server
wraithwall routes                # print the route table
wraithwall sandbox up --profile app-only   # local sandbox launcher
raven scan .
canary-kit mint my-pkg 1.0.0 --type runtime
honeypot-mitre sample.json
dml validate traps.yaml

Configuration

All secrets and infrastructure endpoints come from environment variables (see .env.example). Nothing is hardcoded to a specific deployment.

Documentation

Platform

• LAUNCH.md — Field guide and platform tour
• docs/architecture.md — Architecture overview
• docs/deployment.md — Deployment guide
• docs/api.md — API surface
• ROADMAP.md — Direction and priorities
• docs/COMMUNITY_ROADMAP.md — Community roadmap
• docs/knowledge-pipeline/ — Technical knowledge articles
• CHANGELOG.md — Version history
• SECURITY.md — Vulnerability reporting

Local sandbox — the optional hardened environment for running the platform on your own machine with synthetic telemetry:

./sandbox.sh up --profile app-only       # T0: gates + state only, no containers
./sandbox.sh destroy --yes               # profiles don't switch in place — clean T0 first
./sandbox.sh up --profile local-sandbox  # T1: build, boot, self-check (one-time ack)
./sandbox.sh verify                      # score the RUNNING sandbox against the checklist
./sandbox.sh destroy --yes               # stop services and delete all sandbox state

Read docs/sandbox/security-model.md first — it states what the sandbox does not isolate. The local sandbox is not a malware-containment environment and not a production deployment; the uplink is a convenience, not an isolation boundary. Hostile content belongs in the T2 research-sandbox profile only (see CONTRIBUTING.md § local sandbox).

Sandbox docs:

• docs/sandbox/quickstart.md — Local sandbox in five minutes
• docs/sandbox/security-model.md — What is isolated, what is not (read this first)
• docs/sandbox/profiles.md — Profiles T0–T3 and confirmation gates
• docs/sandbox/lifecycle.md — up / status / verify / replay / reset / destroy
• docs/sandbox/troubleshooting.md — E-code catalog → cause → fix
• docs/sandbox/network.md — Zones, default-deny, how to verify nothing leaves
• docs/sandbox/data-policy.md — What may enter or leave, synthetic marking
• docs/sandbox/vs-production.md — How the sandbox differs from the production deployment
• docs/sandbox/platforms.md — Platform support matrix
• DEVELOPER_DOCUMENTATION_PLAN.md — Documentation contracts and freshness rules

Contributing

Install the full stack with ./install.sh, run pytest, then open a PR. Each package under packages/ has its own README and examples. See CONTRIBUTING.md for details.

Working on the local sandbox? Read CONTRIBUTING.md § local sandbox first — it states which profile to test hostile content against.

License

MIT — © 2026 Niffyhunt. See LICENSE.