SignalMoat
An open-source agent firewall and early-warning layer for web apps. Know which AI agent is calling your app, decide what each one may do, and get an alert within seconds when someone probes your app, brute-forces logins or replays a stolen session.
Status: alpha (0.4). Start in
monitormode. APIs may change before 1.0. SignalMoat was called SentryCove up to version 0.2.1; see the changelog for what to rename.
New here? Follow the Getting Started guide — install, write a policy, plug it in, get alerts — for Python, Node, ASP.NET Core or any app via the reverse proxy.
Why
Bot traffic is no longer "bot vs human". AI agents browse with real browsers from cloud infrastructure, antidetect browsers replay stolen session cookies, and User-Agent strings prove nothing. SignalMoat answers three questions on every request:
- Who is this? A cryptographically verified AI agent (Web Bot Auth / RFC 9421), a self-declared bot, a script, or an ordinary browser.
- Is it allowed to do this? Per-agent rules: e.g. verified agents may read docs; unverified bots may not submit forms.
- Is something attacking us right now? Honeypot hits, credential stuffing, session hijacking, forged agent signatures → alert to Slack, a webhook or your logs.
Pick your integration
One detection engine, four ways to put it in front of your app:
| Your app | Use | Code change |
|---|---|---|
| Anything (PHP, Java, Go, Ruby, Rails, WordPress, ...) | Reverse proxy (Docker) | none |
| Python: FastAPI, Starlette, any ASGI app | ASGI middleware | one line |
Node: Express, Next.js, Hono, plain http |
clients/node |
a few lines |
| ASP.NET Core (.NET 8 / 10) | clients/dotnet |
a few lines |
All four read the same policy file — copy examples/signalmoat.yaml
and adjust the paths.
Reverse proxy (any language)
client ──> your TLS terminator ──> signalmoat proxy ──> your app
docker build -t signalmoat .
docker run -p 8080:8080 --add-host=host.docker.internal:host-gateway \
-e SIGNALMOAT_UPSTREAM=http://host.docker.internal:3000 \
-v "$PWD/signalmoat.yaml:/etc/signalmoat/signalmoat.yaml:ro" \
signalmoat
or docker compose -f deploy/docker-compose.yml up --build for a complete
example. Without Docker: pip install ".[server]" then
signalmoat proxy --upstream http://127.0.0.1:3000 --config signalmoat.yaml.
Your app receives two extra headers it can trust (client-sent copies are
removed): X-SignalMoat-Agent (e.g. verified:example-agent,
automation:curl) and X-SignalMoat-Client-IP. Make sure the app is only
reachable through the proxy.
Python (FastAPI / Starlette / ASGI)
from fastapi import FastAPI, Request
from signalmoat import SignalMoat
app = FastAPI()
app.add_middleware(SignalMoat, config="signalmoat.yaml")
@app.get("/")
def home(request: Request):
return {"caller": request.state.signalmoat.label} # e.g. "declared:GPTBot"
Node and ASP.NET Core
These use a thin middleware that asks a local SignalMoat service (the "decision API") for a verdict — about 1 ms per request on localhost in our measurement:
export SIGNALMOAT_API_TOKEN=$(python -c "import secrets; print(secrets.token_urlsafe(32))")
signalmoat sidecar --config signalmoat.yaml # or deploy/docker-compose.sidecar.yml
// Express
import { signalmoat } from "signalmoat/express";
app.use(signalmoat({ url: "http://127.0.0.1:8787", token: process.env.SIGNALMOAT_API_TOKEN }));
// ASP.NET Core
builder.Services.AddSignalMoat(o => { o.Url = new Uri("http://127.0.0.1:8787"); o.Token = token; });
app.UseSignalMoat();
See clients/node (including Next.js) and
clients/dotnet for details.
What it detects
| Detection | Signal | Default action |
|---|---|---|
| Verified AI agent | Valid Web Bot Auth signature from a trusted signer | Classified verified, rules decide |
| Forged / replayed agent signature | Signature fails or nonce reused | High alert |
| Bots on sensitive endpoints | Rule match (e.g. unverified bot POSTing a form) | Alert; block in enforce |
| Probing / scanning | Request to a honeypot path (/.env, /.git/*…) |
Critical alert; IP ban in enforce |
| Brute force | N failed logins from one IP in a window | High alert |
| Credential stuffing | Site-wide spike of failed logins | Critical alert |
| Session hijack | Session cookie reused from a different browser/device | High alert |
| Fake browser | User-Agent claims a browser, JA4 TLS fingerprint says HTTP library (JA4) | Medium alert |
| Known-bad TLS client | Rule with a ja4 pattern matches the client's TLS fingerprint |
Alert; block in enforce |
Several workers or hosts: shared state in Redis
By default each SignalMoat process keeps its own bans, counters, used signature nonces and session fingerprints. With several workers or hosts, point them all at one Redis (or Valkey) server so a ban, a brute-force count or a replayed nonce is seen everywhere:
state:
backend: redis # default: memory
redis_url_env: SIGNALMOAT_REDIS_URL # env var holding redis:// or rediss:// URL (may include a password)
key_prefix: "signalmoat:"
timeout_seconds: 0.25
pip install "signalmoat[redis]" (the container image already includes it).
Every update is one atomic server-side script, so concurrent workers never
lose a count or accept a nonce twice; every key expires. Alerts raised by
several workers for the same event are sent once. If Redis cannot be reached,
SignalMoat stops trying for a few seconds (no request waits on a dead server)
and fail_open decides what happens to traffic.
WebSockets
WebSocket connections are screened like any other request: the opening
handshake goes through the same rules, honeypots and bans, and a refused
handshake never reaches your app. The reverse proxy then relays messages in
both directions (text, binary, subprotocols and close codes are preserved);
the ASGI middleware screens FastAPI/Starlette WebSocket endpoints. In
enforce mode an open connection is closed (code 1008) if its client IP is
banned later, e.g. after it hits a honeypot.
websocket:
enabled: true # false refuses all WebSocket handshakes
ban_recheck_seconds: 15 # how often open connections are re-checked
max_message_bytes: 1048576
JA4 TLS fingerprints
A JA4 fingerprint describes the client's
TLS handshake, which is much harder to fake than a User-Agent. SignalMoat
does not terminate TLS, so your TLS terminator computes JA4 and passes it in
a header (Cloudflare: the cf-ja4 managed header; HAProxy or nginx with a
JA4 module: a header you set). Configure that proxy to overwrite the
header, and tell SignalMoat a trusted proxy is in front — otherwise a client
could send the header itself:
trusted_proxy_hops: 1 # required for ja4
ja4:
enabled: true
header: cf-ja4
alert_on_browser_mismatch: true
rules:
- name: block-known-scraper-tls
ja4: ["t13d190900_9dc949149365_*"] # '*' wildcard
action: block
severity: high
Malformed values are ignored. The browser-mismatch alert only fires on combinations real browsers never produce (no ALPN over TCP, TLS below 1.2).
AI alert triage (optional)
Important alerts can arrive with a short, plain-language note — what happened, how bad it is, what to do — written by an LLM:
alerts:
triage:
enabled: true
provider: anthropic # or openai (any OpenAI-compatible API, incl. Ollama / vLLM)
model: claude-haiku-5-5
api_key_env: ANTHROPIC_API_KEY
min_severity: high
max_per_hour: 60 # cost cap
timeout_seconds: 8
max_tokens: 2048 # newer Claude models think first; this covers thinking + answer
effort: low # anthropic only; set to null for older models
# base_url: http://127.0.0.1:11434/v1 # local model; http only on localhost
The note is advisory: triage never blocks, bans or changes an alert's
severity or routing, and if the model is slow, down, over budget or answers
oddly, the alert is delivered unchanged. Alert fields written by the client
(path, User-Agent, ...) reach the model only as quoted, length-limited data it
is told not to obey; its answer must be a small JSON object, and links and
chat mentions are removed from it. A note that plays an alert down by more
than one level ("Low" for a critical alert) is withheld and logged as likely
prompt injection. Only the client's network (/24 or /48) is
sent unless you set include_client_ip: true.
Rollout: monitor → enforce
- Deploy with
mode: monitor. Nothing is blocked; you only get alerts. - Tune rules and honeypot paths until alerts are meaningful.
- Switch to
mode: enforce. Blocking applies toblockrules, honeypots and bans.
By default SignalMoat fails open: a bug or outage in SignalMoat never takes
your app down. Set fail_open: false (and failOpen / FailOpen in the Node
and .NET middleware) if you prefer requests to be refused instead.
Security design
- Rules cannot be dodged with path tricks. Paths are matched in a canonical
form, so
/LOGIN,/login/,//login,/lo%67inand/x/../loginall hit a rule on/login. - No SSRF: key directories are fetched only from origins you list under
web_bot_auth.trusted_agents, over HTTPS, without redirects, size-capped. - Spoof-resistant client IP:
X-Forwarded-Foris ignored unless you settrusted_proxy_hops, and then only the proxy-written entry is used. The reverse proxy strips forged forwarding andX-SignalMoat-*headers. - Unknown addresses are never banned: if the client address cannot be determined, IP bans and per-IP counters are skipped rather than applied to everyone at once.
- Decision API is authenticated: every call needs a bearer token, compared in constant time; it binds to localhost by default.
- Bounded memory: every tracker is size-capped and expires — in Redis too, where attacker-supplied keys (e.g. nonces) are hashed to a fixed length.
- Privacy: session tokens are stored only as truncated SHA-256 hashes; raw tokens never appear in alerts. Webhook URLs come from environment variables.
- Strict config: unknown keys are rejected so a typo cannot silently disable a protection.
Limitations (honest list)
- State is per process unless you enable the Redis backend.
- Reverse proxy: no TLS termination (run it behind your load balancer, Caddy or nginx), and it is a single Python process per worker — fine for small and medium sites, not a CDN.
- WebSockets are screened by the reverse proxy and the ASGI middleware. The Node and .NET middleware do not see WebSocket upgrades yet; put the reverse proxy in front if you need them screened.
- JA4 needs a TLS terminator that computes it; SignalMoat only reads it.
- Next.js / edge runtimes cannot see the response status, so failed-login
monitoring needs the Express middleware or the reverse proxy; see
clients/nodefor how the client address is determined. - Session-hijack detection compares User-Agent and Accept-Language, so a browser auto-update can cause a false positive. It alerts; it never blocks.
- Web Bot Auth is an IETF draft; the verifier implements Ed25519 signatures
with
@method,@authority,@scheme,@path,@queryand header components (including;key=dictionary members). Key-directory response signatures are not yet verified (HTTPS to a trusted origin is relied on). - Behind a proxy that rewrites
Host, signatures covering@authoritywill fail to verify — preserve the original Host header.
Roadmap
-
Publish to PyPI, npm, NuGet and a container registry— ✅ Completed -
Shared state via Redis; WebSocket proxying; JA4 TLS fingerprints— ✅ Completed -
LLM-assisted alert triage: plain-language "what happened, how bad, what to do"— ✅ Completed - Optional hosted console: fleet view, shared threat intelligence, team alert routing
Repository layout
src/signalmoat/ engine, ASGI middleware, reverse proxy, decision API, CLI (Python)
clients/node/ Express middleware and Next.js / fetch guard (TypeScript)
clients/dotnet/ ASP.NET Core middleware (C#)
deploy/ Docker Compose examples
examples/ example policy and FastAPI app
Development
pip install -e ".[dev]"
pytest
ruff check src tests && mypy --ignore-missing-imports src
(cd clients/node && npm ci && npm test)
dotnet run -c Release --project clients/dotnet/tests/SignalMoat.AspNetCore.Tests
Releases are described in RELEASING.md.
The Node and .NET suites start the real decision API and run the middleware
against it. The Python suite includes real-socket reverse-proxy tests, an
interoperability test that verifies signatures produced by the independent
http-message-signatures library, and the RFC 8037 JWK-thumbprint vector.
License
Apache-2.0. Contributions require agreeing to the CLA — see CONTRIBUTING.md. Report vulnerabilities privately as described in SECURITY.md.
Metadata
Release files for signalmoat 0.4.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| signalmoat-0.4.0.tar.gz | 84.2 kB | With provenance | Details for signalmoat-0.4.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| signalmoat-0.4.0-py3-none-any.whl | Python 3 | none | any | Details for signalmoat-0.4.0-py3-none-any.whl |
Total release size: 146.9 kB
Release files / signalmoat-0.4.0.tar.gz
| Download URL | signalmoat-0.4.0.tar.gz |
|---|---|
| Size | 84.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f76f1dbc5a51a2260324970cf89b4b66ce9466cb7b8816b3fead662e9bdc0f7c
|
|
BLAKE2b-256 checksum How to use checksums |
265a0faa1e7220e622c95b7c1cc979282bf7e792cb9244dc2fada265198aa1b7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.
Transparency logRelease files / signalmoat-0.4.0-py3-none-any.whl
| Download URL | signalmoat-0.4.0-py3-none-any.whl |
|---|---|
| Size | 62.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
bad5a5cb26ac7144541e395a9f02766fb0c5d785e28b67a9df6477228684a276
|
|
BLAKE2b-256 checksum How to use checksums |
121218034531e749f8366ac66349b1a1bbdb888b79b94749c21e144f15b41518
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.
Transparency logSecurity for signalmoat 0.4.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for signalmoat-0.4.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.