WraithWall

Production deception-and-threat-intelligence platform and companion packages.

Ecosystem

Packages are independent — none imports another.

Quick start

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

Run the local secure sandbox

The sandbox ships in this package: sandbox_kit/ (launcher), compose.sandbox.yml, digest-pinned Dockerfiles, and a deterministic synthetic-telemetry seed. No cloud account, no API keys, no internet exposure.

./sandbox.sh up --profile app-only      # T0: gates + state only, no containers
./sandbox.sh up --profile local-sandbox # T1: build, boot, self-check (one-time ack)
./sandbox.sh verify                     # fail-closed self-check of the running sandbox
./sandbox.sh destroy --yes              # stop services and delete all sandbox state

Every command is fail-closed: a missing prerequisite, a digest mismatch or an ambiguous confirmation stops the launcher instead of starting something inert. Telemetry it produces is synthetic and marked LOCAL on every record, so it can never be mistaken for attacker data.

This is not a guaranteed malware-containment environment unless separately isolated by a VM or dedicated host. Read docs/sandbox/quickstart.md and docs/sandbox/security-model.md before pointing it at anything you did not write yourself.

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
wraithwall serve --port 8000
wraithwall routes
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

• 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
• CHANGELOG.md — Version history
• 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.