docs: add enterprise evaluation guide (#53)

Author: peg

ARCHITECTURE.md

@@ -82,7 +82,7 @@ Device IDs are server-assigned via `POST /api/devices` — clients cannot choose
 3. Fire all webhooks in parallel via `Promise.allSettled`
 4. Failures logged to CF Workers Logs but don't affect the response
 
-Outbound webhook requests include `X-Snare-Signature: sha256=<hmac>` when `WEBHOOK_SIGNING_SECRET` CF secret is configured. Receivers can verify alerts came from snare.sh.
+Outbound webhook requests include `X-Snare-Signature: sha256=<hmac>` when the Cloudflare Worker `WEBHOOK_SIGNING_SECRET` secret is configured. Receivers can verify alerts came from the configured Snare callback deployment.
 
 **Supported webhook formats:** Discord (embed), Slack (attachment), Telegram (HTML), generic JSON (`event: "canary.fired"`).
 

CHANGELOG.md

@@ -12,6 +12,8 @@ Versioning: [Semantic Versioning](https://semver.org/)
 ### Added
 - `snare prove --output <path>` for writing proof reports as shareable artifacts.
 - `snare prove --redact` for share-safe proof reports that remove device IDs, token IDs, labels, cleanup tokens, and absolute local paths.
+- Enterprise evaluation, self-hosting, and SIEM integration guides for security-review-friendly pilots.
+- `snare serve --help` for self-hosted callback server flag discovery.
 
 ### Changed
 - Proof reports now include event visibility, observed callback latency, and explicit “what this proves” / “what this does not prove” sections.

README.md

@@ -110,6 +110,8 @@ snare arm --all --webhook https://discord.com/api/webhooks/YOUR/WEBHOOK
 
 Supported webhook destinations: Discord, Slack, Telegram, or any endpoint that accepts JSON. Treat webhook URLs as secrets — don't commit, screenshot, or share them.
 
+Evaluating Snare for a team or lab? Start with the [enterprise evaluation guide](docs/enterprise-evaluation.md), then wire alerts to your SIEM with the [webhook integration docs](docs/integrations/generic-webhook.md).
+
 ---
 
 ## Commands
@@ -258,7 +260,9 @@ Each alert includes:
 - User agent (identifies the exact SDK: `Boto3/1.34.46`, `kubectl/v1.35.1`, etc.)
 - "Likely AI agent" flag when the request comes from cloud infrastructure
 
-Alerts are signed with `X-Snare-Signature` (HMAC-SHA256) so you can verify they came from snare.sh.
+Alerts are signed with `X-Snare-Signature` (HMAC-SHA256) when webhook signing is configured, so receivers can verify the sender.
+
+See [generic webhooks](docs/integrations/generic-webhook.md), [Splunk](docs/integrations/splunk.md), [Datadog](docs/integrations/datadog.md), and [Microsoft Sentinel](docs/integrations/sentinel.md) for SIEM integration patterns.
 
 ---
 
@@ -302,27 +306,29 @@ Fake credential content lives locally in `~/.snare/manifest.json` (0600) and is
 
 ## Self-hosting
 
-The Cloudflare Worker is open source in this repo (`worker/`). Deploy it to your own account:
+Use self-hosting when you need a custom callback domain, full network-layer control, private retention, or SIEM relay behavior. The repo includes both the Cloudflare Worker source (`worker/`) and a standalone `snare serve` path with Docker Compose.
+
+Quick standalone server:
 
 ```sh
-cd worker
-npx wrangler deploy
+SNARE_DASHBOARD_TOKEN="$(openssl rand -hex 32)" \
+  snare serve --port 8080 --db /var/lib/snare/snare.db
 ```
 
-Set `WEBHOOK_URLS` as a Cloudflare Worker secret for alert delivery. Set `WEBHOOK_SIGNING_SECRET` to sign outbound requests.
-
-To point canaries at your own server instead of snare.sh, edit `callback_base` in `~/.snare/config.json` after `snare init`.
-
-`snare serve` requires `--dashboard-token` (or `SNARE_DASHBOARD_TOKEN`) to protect the dashboard. Generate one with `openssl rand -hex 32`.
-
-Docker Compose can use `.env.example` as a starting point:
+Quick Docker Compose path:
 
 ```sh
-cp .env.example .env
-SNARE_DASHBOARD_TOKEN="$(openssl rand -hex 32)" docker compose up -d
+{
+  echo "SNARE_DASHBOARD_TOKEN=$(openssl rand -hex 32)"
+  echo "SNARE_PORT=8080"
+} > .env
+docker compose up -d
+curl -fsS http://localhost:8080/health
 ```
 
-> **Important:** Only expose `snare serve` behind a reverse proxy you control (nginx, Caddy, Cloudflare Tunnel). Never bind directly to a public interface. By default the server ignores `X-Forwarded-For` and `X-Real-IP`. If you want real client IP attribution behind a trusted proxy, set `--trusted-proxy <cidr,...>` to the proxy network(s) that are allowed to supply those headers.
+Only expose `snare serve` behind a reverse proxy you control. By default the server ignores `X-Forwarded-For` and `X-Real-IP`; set `--trusted-proxy <cidr,...>` only for proxy networks that are allowed to supply those headers.
+
+See the [self-hosting guide](docs/self-hosting.md) for reverse proxy, backup, upgrade, Cloudflare Worker, and client `callback_base` steps.
 
 ---
 

SECURITY.md

@@ -35,6 +35,8 @@ Out of scope:
 
 **Privacy guarantee:** The `/c/{token}` callback endpoint never reads, stores, or forwards request bodies. Only header-derived metadata is stored (IP, user agent, timestamp, ASN). This applies to the managed snare.sh worker. Self-hosted deployments are controlled by the operator.
 
+For a team/security review checklist covering data flow, files touched, proof artifacts, SIEM routing, and cleanup, see [docs/enterprise-evaluation.md](docs/enterprise-evaluation.md).
+
 **Device secret:** The CLI generates a 256-bit device secret at `~/.snare/config.json` (0600 permissions). This secret authenticates API calls to snare.sh. If compromised, run `snare rotate` immediately.
 
 ## Supported Versions

docs/README.md

@@ -0,0 +1,10 @@
+# Snare docs
+
+These docs are written for security engineers evaluating, piloting, or operating Snare beyond a single local test.
+
+- [Enterprise evaluation](enterprise-evaluation.md) — data flow, files touched, safe pilot checklist, proof artifact workflow, and limitations.
+- [Self-hosting](self-hosting.md) — Docker Compose, `snare serve`, Cloudflare Worker deployment notes, reverse proxy guidance, backups, and upgrades.
+- [Generic webhooks](integrations/generic-webhook.md) — event schema, signature verification, and relay guidance.
+- [Splunk integration](integrations/splunk.md) — Splunk HEC relay pattern and field mapping.
+- [Datadog integration](integrations/datadog.md) — direct Logs intake and monitor examples.
+- [Microsoft Sentinel integration](integrations/sentinel.md) — Log Analytics relay pattern and KQL examples.

docs/enterprise-evaluation.md

@@ -0,0 +1,155 @@
+# Enterprise evaluation guide
+
+Snare is intentionally small: a CLI plants credential and tool-use tripwires, callbacks produce alert metadata, and the operator can prove and remove the tripwires. This guide is for security engineers who need to evaluate Snare safely before using it in a lab, developer fleet, CI environment, or AI-agent pilot.
+
+## What Snare does and does not do
+
+Snare detects active use of planted fake credentials and tool configurations. It is not a prompt-injection firewall, EDR, DLP tool, or policy enforcement engine.
+
+Snare is useful when you want to know whether an agent, scanner, script, or human attacker tried to use a sensitive-looking local capability such as an AWS profile, SSH host, kube context, package registry, or SDK endpoint override.
+
+## Recommended safe pilot
+
+Start with the default precision canaries (`awsproc`, `ssh`, `k8s`). They are designed to stay quiet during normal work and fire only when the planted fake profile, host, or context is actively used.
+
+```sh
+# 1. Preview local file changes without writing canaries.
+snare arm --dry-run
+
+# 2. Arm precision-mode canaries and send alerts to an existing destination.
+snare arm --webhook https://example.com/snare-webhook
+
+# 3. Confirm local state and expected quiet state.
+snare status
+snare scan
+snare doctor
+
+# 4. Run an end-to-end test callback and verify event readability.
+snare doctor --test
+
+# 5. Safely trigger precision canaries and write a redacted proof artifact.
+snare prove --run --report --redact --format json --output proof.json
+
+# 6. Review recent callback evidence.
+snare events
+
+# 7. Remove canaries and local Snare config when the pilot is done.
+snare disarm --purge
+```
+
+A fresh canary showing `never fired` can be healthy. Use `snare scan`, `snare doctor`, and `snare prove` to distinguish a healthy quiet canary from a registration or readability problem.
+
+## What files Snare touches
+
+`snare arm` defaults to precision mode and only plants `awsproc`, `ssh`, and `k8s` canaries. `snare arm --all` expands to every canary type.
+
+| Scope | Examples | Notes |
+|---|---|---|
+| Local Snare state | `~/.snare/config.json`, `~/.snare/manifest.json` | Created with restrictive permissions. Manifest records exact bytes written for safe teardown. |
+| Precision canaries | `~/.aws/config`, `~/.ssh/config`, `~/.kube/<name>.yaml` | Default mode. Designed to fire on active use, not passive reads. |
+| Package/tool canaries | `~/.npmrc`, `~/.config/pip/pip.conf`, `~/.gitconfig`, `~/.terraformrc`, `~/.docker/config.json` | Use selectively. Some package-manager canaries may fire during normal developer workflows. |
+| SDK/app canaries | dotenv files and vendor config files for OpenAI, Anthropic, GCP, Azure, GitHub, Stripe, Hugging Face, MCP, and generic endpoints | These depend on how the target agent or tool consumes local config. |
+
+Teardown is content-matched: Snare removes the exact bytes it wrote and does not rewrite unrelated credentials in the same file. Use `snare teardown --dry-run`, `snare disarm`, or `snare disarm --purge` during evaluation cleanup.
+
+## Data flow
+
+### Managed `snare.sh`
+
+1. The CLI creates a local device secret and registers token metadata with `snare.sh`.
+2. A planted canary contains a callback URL such as `https://snare.sh/c/<token>`.
+3. If the fake credential/tool path is used, the SDK or tool requests the callback URL.
+4. The callback service stores metadata and optionally forwards an alert to your webhook destination.
+5. The CLI reads recent events with the local device secret.
+
+### What leaves the machine
+
+| Flow | Data |
+|---|---|
+| Registration API | Token ID, device ID, canary type, label, webhook routing metadata. |
+| Events API | Token ID in the URL and bearer device secret for authenticated reads. |
+| Canary callback | Token ID, request path, method, IP, user agent, Cloudflare-derived geography/ASN/bot metadata when using the managed worker. |
+| Webhook delivery | Alert payload containing event metadata. No request body is included. |
+
+Callback handlers intentionally do not read, store, or forward request bodies. This matters because some SDK callbacks can include credential material in HTTP bodies. The application-level privacy guarantee does not mean Cloudflare or other network infrastructure never handles the encrypted network request; self-host if you need full network-layer control.
+
+## Proof artifact workflow
+
+Use proof reports as the shareable evaluation artifact:
+
+```sh
+snare prove --run --report --redact --format json --output proof.json
+```
+
+A useful proof artifact should show:
+
+- which precision canaries were armed;
+- which trigger commands were executed;
+- whether callbacks were visible through the events API;
+- observed callback timestamps and latency where available;
+- cleanup commands;
+- what the proof demonstrates;
+- what the proof does not demonstrate.
+
+Use `--redact` before sharing outside the evaluating machine. Redaction removes raw device IDs, token IDs, labels, cleanup-token values, and local absolute paths.
+
+## Webhooks and SIEMs
+
+Snare can post alerts to Discord, Slack, Telegram, or generic JSON webhook endpoints. For SIEMs that require custom headers, signed requests, or vendor-specific envelope formats, put a small relay in front of the SIEM and have Snare post to the relay.
+
+See:
+
+- [Generic webhooks](integrations/generic-webhook.md)
+- [Splunk](integrations/splunk.md)
+- [Datadog](integrations/datadog.md)
+- [Microsoft Sentinel](integrations/sentinel.md)
+
+## Self-hosting decision
+
+Use managed `snare.sh` for a quick lab. Self-host when you need one or more of the following:
+
+- all callback traffic to stay inside your network or cloud account;
+- a custom callback domain;
+- control over log retention, backup, and alert routing;
+- custom webhook signing or relay behavior;
+- evaluation in a restricted enterprise lab.
+
+See [Self-hosting](self-hosting.md).
+
+## Release and install verification
+
+For production-like pilots, verify the release before installing broadly:
+
+```sh
+cosign verify-blob --bundle checksums.txt.bundle checksums.txt
+sha256sum -c checksums.txt
+```
+
+Then smoke-test the binary in a temporary install directory before deploying to endpoints:
+
+```sh
+snare --version
+snare arm --help
+snare doctor --help
+snare prove --help
+```
+
+## Known limitations to include in review
+
+- Snare detects use of planted tripwires; it does not prevent compromise.
+- `~/.snare/manifest.json` records canary locations so Snare can safely remove them. A local attacker who reads it can identify bait.
+- Public callback domains can be fingerprinted. Use self-hosting or a custom callback domain when that matters.
+- Some canary types are intentionally noisier than the precision defaults and should be selected deliberately.
+- Managed mode depends on the availability and policy of the hosted callback service and its network provider.
+- Webhook URLs are secrets and should be handled like credentials.
+
+## Evaluation checklist
+
+- [ ] `snare arm --dry-run` output reviewed by a security engineer.
+- [ ] Default precision-mode canaries tested before `--all`.
+- [ ] `snare doctor --test` passes in the target network.
+- [ ] `snare prove --run --report --redact --format json --output proof.json` produces a share-safe artifact.
+- [ ] Alert destination tested and owned by the evaluating team.
+- [ ] Cleanup command verified with `snare disarm --purge` on a pilot host.
+- [ ] SIEM relay or direct integration documented, including secret handling.
+- [ ] Self-hosting decision recorded for callback privacy and custom domain requirements.

docs/integrations/datadog.md

@@ -0,0 +1,89 @@
+# Datadog integration
+
+Datadog Logs intake can accept the API key in the URL path, so Snare can send generic JSON directly. Use a relay instead if your organization forbids secrets in webhook URLs or requires request signing before ingestion.
+
+## Direct Logs intake
+
+Use the Datadog site that matches your account.
+
+US site example:
+
+```sh
+snare config set webhook 'https://http-intake.logs.datadoghq.com/v1/input/<DATADOG_API_KEY>?ddsource=snare&service=snare&ddtags=team:security,env:pilot'
+snare doctor --test
+```
+
+EU site example:
+
+```sh
+snare config set webhook 'https://http-intake.logs.datadoghq.eu/v1/input/<DATADOG_API_KEY>?ddsource=snare&service=snare&ddtags=team:security,env:pilot'
+snare doctor --test
+```
+
+Treat the configured webhook URL as a secret because it contains the Datadog API key.
+
+## Recommended facets
+
+Create facets or measures from these JSON fields:
+
+| Datadog facet | Snare JSON path |
+|---|---|
+| `@event` | `event` |
+| `@canary_type` | `canary_type` |
+| `@label` | `label` |
+| `@device_id` | `device_id` |
+| `@ip` | `ip` |
+| `@network.org` | `network.org` |
+| `@network.asn` | `network.asn` |
+| `@network.is_cloud` | `network.is_cloud` |
+| `@request.user_agent` | `request.user_agent` |
+| `@is_test` | `is_test` |
+
+## Example log queries
+
+Real canary fires:
+
+```text
+service:snare @event:canary.fired @is_test:false
+```
+
+Cloud-hosted source:
+
+```text
+service:snare @event:canary.fired @is_test:false @network.is_cloud:true
+```
+
+Specific canary type:
+
+```text
+service:snare @canary_type:awsproc @is_test:false
+```
+
+## Monitor example
+
+Create a Logs monitor with query:
+
+```text
+logs("service:snare @event:canary.fired @is_test:false").index("*").rollup("count").last("5m") > 0
+```
+
+Notification text:
+
+```text
+Snare canary fired.
+
+Type: {{log.attributes.canary_type}}
+Label: {{log.attributes.label}}
+IP: {{log.attributes.ip}}
+Network: {{log.attributes.network.org}}
+User-Agent: {{log.attributes.request.user_agent}}
+```
+
+## Validation
+
+```sh
+snare doctor --test
+snare prove --run --report --redact --format json --output proof.json
+```
+
+Confirm `is_test:true` appears for the doctor test and `is_test:false` appears for proof callbacks.