README
¶
WebSec0
WebSec0 is an open-source, self-hostable, passive web security
configuration scanner. In a single ~15 MB binary, it inspects a host's TLS
configuration and HTTP security headers, runs a handful of custom checks
(security.txt, robots.txt, …), and produces actionable reports with
copy-paste remediation snippets.
Built for two audiences at parity:
- Humans — clear reports prioritized by ROI (security ÷ effort)
- AI agents — every finding is self-sufficient (no external fetch needed),
the catalog is exposed via
GET /api/v1/checks, and a ready-to-useSKILL.mdis shipped
Try it
Hosted instance: www.websec0.com — no signup, no key, public.
Or call the API directly:
curl -sS -X POST https://www.websec0.com/api/v1/scan \
-H 'Content-Type: application/json' \
-d '{"host":"github.com"}' | jq .
The full request/response contract, error envelope and grading model are
documented in SKILL.md — written for AI agents
but human-readable.
Self-host
Pull and run the published multi-arch image. Defaults work out of the box:
docker run --rm -p 8080:8080 ghcr.io/joshuamart/websec0:latest
Open http://localhost:8080. The distroless image weighs ~15 MB and runs as a non-root user. To override the defaults (listen address, rate limits, SSRF policy, history retention), mount a config file:
docker run --rm -p 8080:8080 \
-v "$(pwd)/websec0.yaml":/etc/websec0/websec0.yaml:ro \
ghcr.io/joshuamart/websec0:latest \
--config /etc/websec0/websec0.yaml
Use websec0.yaml.example as a starting point —
every field is annotated.
Build the image yourself
The repo ships two Dockerfiles. Dockerfile builds Go inside Docker and is
what make docker invokes; Dockerfile.goreleaser is the minimal copy-only
runtime used by the release pipeline.
docker build -t websec0 .
docker run --rm -p 8080:8080 websec0
From source
Requires Go 1.26+, Node 22+, pnpm 10+, and rsync.
make frontend-install
make build
./dist/websec0
make build declares the embedded Astro bundle as a Make prerequisite,
so it rebuilds the frontend (and rsyncs it into internal/frontend/dist/
where //go:embed picks it up) iff a file under web/ has changed.
Iterative Go-only builds incur no frontend overhead.
How it works
flowchart LR
User[Web UI · curl · agent] -->|POST /api/v1/scan| API[chi router + rate limit]
API --> SSRF[safehttp gate<br/>IP pin · no private · no rebind]
SSRF --> Orch[Scanner orchestrator]
Orch --> TLS[TLS probe]
Orch --> HDR[Headers probe]
Orch --> Custom[Custom checks]
TLS --> Score[Scoring]
HDR --> Score
Score --> Result["scan.Result<br/>(2 grades + findings)"]
Custom --> Result
Result --> User
Every outbound request goes through safehttp: each target is pinned
to a single IP at DNS-resolution time, RFC 1918 / loopback / link-local
addresses are always refused, and the connection is rate-limited per host.
Probes then fan out in parallel — a typical scan completes in ~10 seconds.
Contributing
See CONTRIBUTING.md for the dev workflow and the
three flavours of "adding a check". Security reports go through the
private channel documented in SECURITY.md.
AI agents integrating WebSec0 should start with
skills/websec0/SKILL.md.
License
MIT for the code. Reports generated by the public instance are published under Creative Commons BY 4.0.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package catalog hosts the machine-readable checks catalog served at GET /api/v1/checks.
|
Package catalog hosts the machine-readable checks catalog served at GET /api/v1/checks. |
|
cmd
|
|
|
websec0
command
Command websec0 is the HTTP scanner daemon.
|
Command websec0 is the HTTP scanner daemon. |
|
internal
|
|
|
api
Package api hosts the HTTP routing layer: a chi router that exposes /api/v1/scan (POST + GET by id) and /api/v1/checks, wired with request-ID, slog request logger, panic recovery and per-IP rate limiting.
|
Package api hosts the HTTP routing layer: a chi router that exposes /api/v1/scan (POST + GET by id) and /api/v1/checks, wired with request-ID, slog request logger, panic recovery and per-IP rate limiting. |
|
cache
Package cache provides a thread-safe TTL + LRU cache used to retain recently completed scan results.
|
Package cache provides a thread-safe TTL + LRU cache used to retain recently completed scan results. |
|
config
Package config loads, validates and exposes the websec0.yaml runtime configuration.
|
Package config loads, validates and exposes the websec0.yaml runtime configuration. |
|
custom
Package custom hosts the non-scoring "additional findings" checks.
|
Package custom hosts the non-scoring "additional findings" checks. |
|
frontend
Package frontend embeds the Astro static build and exposes it as an http.Handler with SPA fallback.
|
Package frontend embeds the Astro static build and exposes it as an http.Handler with SPA fallback. |
|
headers
Package headers fetches and evaluates the HTTP security headers exposed by a target.
|
Package headers fetches and evaluates the HTTP security headers exposed by a target. |
|
history
Package history maintains the opt-in, in-memory list of recently completed public scans.
|
Package history maintains the opt-in, in-memory list of recently completed public scans. |
|
safehttp
Package safehttp is the security-critical core that gates every outbound connection made by a scan.
|
Package safehttp is the security-critical core that gates every outbound connection made by a scan. |
|
scan
Package scan defines the public payload shapes returned by the scanner API.
|
Package scan defines the public payload shapes returned by the scanner API. |
|
scanner
Package scanner is the scan orchestrator.
|
Package scanner is the scan orchestrator. |
|
scoring
Package scoring contains the threshold tables and computation rules that turn observation reports into a 0–100 score and a scan.Grade letter.
|
Package scoring contains the threshold tables and computation rules that turn observation reports into a 0–100 score and a scan.Grade letter. |
|
sslv2
Package sslv2 detects whether a server speaks the obsolete SSLv2 protocol.
|
Package sslv2 detects whether a server speaks the obsolete SSLv2 protocol. |
|
sslv3
Package sslv3 detects whether a server speaks SSLv3 by sending a TLS-framed ClientHello with version 0x0300 and classifying the response.
|
Package sslv3 detects whether a server speaks SSLv3 by sending a TLS-framed ClientHello with version 0x0300 and classifying the response. |
|
tls
Package tls runs the modern TLS probe — protocol enumeration, cipher enumeration per legacy protocol, certificate-chain extraction with system-root validation, OCSP-stapling presence and presence-based weakness heuristics.
|
Package tls runs the modern TLS probe — protocol enumeration, cipher enumeration per legacy protocol, certificate-chain extraction with system-root validation, OCSP-stapling presence and presence-based weakness heuristics. |
|
version
Package version exposes the build-time identifiers (release tag, git commit, build date) injected via -ldflags.
|
Package version exposes the build-time identifiers (release tag, git commit, build date) injected via -ldflags. |