Skip to main content
SignalMoat

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 monitor mode. 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:

  1. Who is this? A cryptographically verified AI agent (Web Bot Auth / RFC 9421), a self-declared bot, a script, or an ordinary browser.
  2. Is it allowed to do this? Per-agent rules: e.g. verified agents may read docs; unverified bots may not submit forms.
  3. 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

  1. Deploy with mode: monitor. Nothing is blocked; you only get alerts.
  2. Tune rules and honeypot paths until alerts are meaningful.
  3. Switch to mode: enforce. Blocking applies to block rules, 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%67in and /x/../login all 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-For is ignored unless you set trusted_proxy_hops, and then only the proxy-written entry is used. The reverse proxy strips forged forwarding and X-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/node for 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, @query and 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 @authority will 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)

Source distribution for signalmoat 0.4.0
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)

Table of built distributions (wheels) for signalmoat 0.4.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page