{"id":51015038,"url":"https://github.com/c0oki3s/veilgate","last_synced_at":"2026-06-21T09:02:31.045Z","repository":{"id":358335646,"uuid":"1233258841","full_name":"C0oki3s/veilgate","owner":"C0oki3s","description":"Asymmetric defense against AI red-team agents. VeilGate scores every request, diverts likely agents into a per-IP-coherent fake application, and measures the cost it imposes on the attacker.","archived":false,"fork":false,"pushed_at":"2026-05-24T17:45:12.000Z","size":898,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-24T19:24:39.736Z","etag":null,"topics":["ai-security","deception","golang","honeypot","ja3","ja4","llm-security","pentest","prompt-injection","reverse-proxy","security","trapit"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/C0oki3s.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":"THREAT_MODEL.md","audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-08T19:06:15.000Z","updated_at":"2026-05-24T17:45:16.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/C0oki3s/veilgate","commit_stats":null,"previous_names":["c0oki3s/veilgate"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/C0oki3s/veilgate","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/C0oki3s%2Fveilgate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/C0oki3s%2Fveilgate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/C0oki3s%2Fveilgate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/C0oki3s%2Fveilgate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/C0oki3s","download_url":"https://codeload.github.com/C0oki3s/veilgate/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/C0oki3s%2Fveilgate/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34603628,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-21T02:00:05.568Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-security","deception","golang","honeypot","ja3","ja4","llm-security","pentest","prompt-injection","reverse-proxy","security","trapit"],"created_at":"2026-06-21T09:02:28.771Z","updated_at":"2026-06-21T09:02:31.027Z","avatar_url":"https://github.com/C0oki3s.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# VeilGate\n\nVeilGate is an open-source deception proxy for teams that want to raise the cost\nof automated security probing without putting fragile block rules in front of\nreal users.\n\nIt sits in front of a web application, scores each request, and chooses one of\nthree outcomes:\n\n- **Real**: forward clean traffic to the upstream app.\n- **Challenge**: ask suspicious-but-ambiguous clients to solve a browser proof of work.\n- **Tarpit**: divert high-confidence agent traffic into a deterministic fake app.\n\nThe goal is not magic invulnerability. The goal is better economics: keep humans\nand normal automation moving, while making AI-assisted scanners spend time,\ntokens, and attention on believable dead ends.\n\n## What It Does\n\n- Reverse proxy with `observe`, `challenge`, `tarpit`, and threshold-driven `auto` modes.\n- Detection signals for suspicious user agents, sparse browser headers,\n  honeypot paths, timing regularity, scanner paths, SQLi/XSS/OOB markers,\n  IP/UA rotation, cookie behavior, request graph shape, JA3/JA4 TLS fingerprints,\n  HTTP/2 fingerprints, canary replay, and online ML scoring.\n- Browser proof-of-work challenge with both **cookie** and **`X-Veilgate-Token`\n  header** transports so cross-origin SPAs can solve and reattach the token\n  on subsequent API calls. The 401 challenge response is SPA-aware: it returns\n  HTML for top-level navigations and JSON (with the PoW metadata to solve\n  inline) for `fetch` / `XHR` contexts.\n- Operator-issued **HMAC verifier chain** for server-to-server clients that\n  cannot solve the PoW (see [docs/how-to/server-to-server-hmac.md](docs/how-to/server-to-server-hmac.md)).\n- Shadow application responses with stable per-client fake profiles.\n- Prompt-injection and decoy payload injection for tarpit responses.\n- SQLite persistence for events, feature rollups, audit logs, and canaries.\n- Prometheus metrics and a lightweight dashboard on the metrics listener.\n- Hot-reloadable YAML rule files, fed by the separate\n  [veilgate-rules](https://github.com/C0oki3s/veilgate-rules) community repository.\n\n## Quick Start\n\n### Option 1 — Install script (recommended)\n\nDownloads the binary, installs a systemd service, installs community rules, and\nwrites a starter config in `observe` mode.\n\n```bash\n# One-liner\ncurl -sSL https://veilgate.dev/install.sh | sudo bash -s -- --upstream http://localhost:3000\n\n# Or download first, then run\ncurl -sSL https://veilgate.dev/install.sh -o install.sh\nsudo ./install.sh --upstream http://localhost:3000\n```\n\nFlags:\n\n| Flag | Default | Description |\n| --- | --- | --- |\n| `--upstream URL` | `http://127.0.0.1:3000` | Your upstream application |\n| `--listen ADDR` | `:8080` | Proxy listen address |\n| `--metrics-listen ADDR` | `127.0.0.1:9090` | Metrics (keep private) |\n| `--secret SECRET` | prompt or generated | Challenge signing secret |\n| `--user USER` | `veilgate` | Service user to run VeilGate |\n| `--no-service` | — | Skip systemd service |\n| `--no-rules` | — | Skip community rules install |\n\nThe packaged config uses `rules_dir: \"~/.veilgate/rules\"`. Under systemd,\nVeilGate runs as the `veilgate` user whose home is `/var/lib/veilgate`, so this\nresolves to `/var/lib/veilgate/.veilgate/rules`.\n\nIf `--secret` is omitted on a new install, the installer prompts on interactive\nterminals and otherwise generates a random secret. If the service user does not\nexist, the installer asks before creating it on interactive terminals and\ndefaults to creation for non-interactive installs.\n\nAfter install:\n\n```bash\nsystemctl status veilgate\njournalctl -u veilgate -f\n```\n\n### Option 2 — Docker\n\n```bash\ndocker run -d --name veilgate \\\n  --network host \\\n  -v /etc/veilgate/veilgate.yaml:/etc/veilgate/veilgate.yaml:ro \\\n  -v ~/.veilgate/rules:/home/nonroot/.veilgate/rules \\\n  -e VEILGATE_SECRET=$(openssl rand -hex 32) \\\n  ghcr.io/c0oki3s/veilgate:latest -config /etc/veilgate/veilgate.yaml\n```\n\n### Option 3 — Build from source\n\nPrerequisite: Go `1.25.10` or newer.\n\n```bash\ngit clone https://github.com/C0oki3s/veilgate.git\ncd veilgate\nmake build\n./veilgate -config configs/veilgate.yaml\n```\n\nBy default VeilGate listens on `:8080`, proxies to `http://localhost:3000`,\nand exposes metrics on `:9090`.\n\nThe default config starts in `observe` mode — baseline normal traffic before\nenabling `challenge` or `tarpit`.\n\n## Operating Modes\n\n| Mode | Use it when | Behavior |\n| --- | --- | --- |\n| `observe` | Initial rollout and tuning | Scores and records traffic, always forwards upstream |\n| `challenge` | You are comfortable interrupting suspicious clients | Medium-score traffic gets proof of work |\n| `tarpit` | You are ready to deceive high-confidence agents | High-score traffic receives the fake app |\n| `auto` | You want thresholds to drive enforcement per request | Forward below threshold, challenge middle scores, tarpit high scores |\n\nRecommended rollout:\n\n1. Run `observe` for at least several days.\n2. Review metrics and event samples for false positives.\n3. Enable `challenge` for ambiguous traffic.\n4. Enable `tarpit` once your thresholds match your environment.\n\n## Configuration\n\nStart with [configs/veilgate.yaml](configs/veilgate.yaml):\n\n```yaml\nlisten: \":8080\"\nupstream: \"http://localhost:3000\"\nmode: \"observe\"\nrules_dir: \"~/.veilgate/rules\"\n\ndetector:\n  score_challenge_threshold: 40\n  score_tarpit_threshold: 70\n  trusted_ips: []\n  trusted_proxies: []\n\nmetrics:\n  listen: \":9090\"\n```\n\nFull reference: [Configuration reference](docs/reference/config-reference.md).\n\n## Rules\n\nVeilGate ships **no embedded rules**. The binary reads `rules_dir` at startup\nand hot-reloads changes; if the directory is empty it starts with zero detection\nsignals. Rules come from one place:\n\n- **[veilgate-rules](https://github.com/C0oki3s/veilgate-rules)** — the\n  community-maintained rule pack. The `install.sh` script clones it\n  automatically on first install. You can also update it manually with the\n  built-in `update-rules` subcommand — no rebuild, no restart:\n\n| | Installs rules automatically? |\n| --- | --- |\n| `install.sh` (first run) | **Yes** — clones via git |\n| `veilgate` binary (startup) | **No** — reads `rules_dir`, never fetches |\n| `veilgate update-rules` | Only when you explicitly call it |\n\n  ```bash\n  # Install the latest pack into ~/.veilgate/rules (the default location)\n  veilgate update-rules\n\n  # Or pin to a release tag\n  veilgate update-rules --dir ~/.veilgate/rules --version v1.2.0\n\n  # List available releases\n  veilgate update-rules --list\n  ```\n\n  After the install, VeilGate's `fsnotify` watcher picks up the new files\n  within ~500 ms. Each existing file is backed up as `\u003cname\u003e.bak` before\n  being overwritten (pass `--no-backup` to skip). The installed version is\n  recorded in `\u003crules_dir\u003e/.rules-version.json` so CI and operators can\n  check what is running without consulting git metadata.\n\n  Treat both directories as security policy — review changes before\n  deploying to production, especially `detector.yaml` and `ip_reputation.yaml`.\n  Full guide and rollback procedure:\n  [docs/how-to/install-community-rules.md](docs/how-to/install-community-rules.md).\n\n## Documentation\n\n- [Getting Started](docs/getting-started/README.md): local run and first checks.\n- [Configuration Reference](docs/reference/config-reference.md): `veilgate.yaml` and rule files.\n- [Deployment](docs/deployment/README.md): Linux/systemd installation.\n- [Architecture](docs/architecture/README.md): request flow and subsystem design.\n- [Operations](docs/operations/README.md): metrics, dashboards, alerts, routine checks.\n- [Model Card](docs/model/README.md): ML signal behavior and limitations.\n- [Reference Index](docs/reference/README.md): complete lookup-oriented reference pages.\n- [Community Rules](docs/how-to/install-community-rules.md): install and update community-maintained rule sets via `veilgate update-rules`.\n- [Threat Model](THREAT_MODEL.md): what VeilGate does and does not protect.\n\n## Security Notes\n\n- Only deploy VeilGate in front of systems you own or operate.\n- Do not expose the metrics listener directly to the public internet.\n- Set `VEILGATE_SECRET` or `challenge.secret` before using `challenge` or\n  `tarpit` mode. VeilGate refuses to start outside `observe` mode with the\n  default challenge secret.\n- Treat files under `rules/` as security policy. Review and version them.\n- Start with conservative thresholds and tune from observed traffic.\n\n## Development\n\n```bash\nmake test\nmake fmt\nmake build\n```\n\nThe top-level [tests](tests) folder contains black-box integration tests.\nPackage-private unit tests live next to their packages because they verify\nunexported detector, TLS fingerprint, tarpit, and ML helpers.\n\n## License\n\nApache-2.0. See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fc0oki3s%2Fveilgate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fc0oki3s%2Fveilgate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fc0oki3s%2Fveilgate/lists"}