Repository: sharifndlovu123/siteward · MIT licence · Python 3.11+ Get it: git clone https://github.com/sharifndlovu123/siteward.git && cd siteward && pip install . then siteward scan https://your-site.example (or run the Docker image / local web UI, see the repo README). Only scan sites you own or may test.

Siteward is a small, self-hostable passive web security scanner: give it a URL, it runs standard checks and reports findings as Markdown, JSON or a self-contained HTML file. Nothing about scanned sites is stored. Source: the siteward repo. Use it only on sites you run or have explicit permission to test; it is a routine-coverage tool, not a replacement for a manual penetration test.

Tools at a glance

$ pip install .
$ siteward scan https://example.com
$ siteward scan https://example.com --format html --out report.html
$ siteward scan https://example.com --ports --fail-on medium     # exits 1 in CI if medium or worse

What It Checks (and Why Each Matters)

Active tests such as XSS or injection probes are planned for a later version, behind an ownership check.

Architecture: A Complexity Budget

The design rule: small enough to read in an afternoon, cheap enough to host on the smallest box. Every piece must earn its place.

flowchart TD
    W[web/ - Django] --> C[core/ - validate, fetch once, run checks, ScanReport]
    L[cli/ - Typer] --> C
    C --> K[checks/ - one file per check]
    C --> R[reports/ - json, html, markdown]
    C --> N[netguard - SSRF protection and rate limits]

Dependency rule: arrows only point downward. core/ and checks/ never import Django or Typer, and web/ and cli/ never hold scan logic.

The plugin contract

A check is just a module, no base class or registry:

# checks/security_headers.py
ID = "headers.security"
CATEGORY = "Headers"
NEEDS_OPT_IN = False          # True only for the port check

def run(ctx: ScanContext) -> list[Finding]:
    ...

• The runner discovers every module in checks/ automatically
• A check returns findings, or an empty list for "fine"; if it raises, the runner records an error result
• The page is fetched once into a shared ScanContext so checks do not each re-request it
• Findings are plain dataclasses: Finding(id, title, category, severity, evidence, remediation); grade and severity counts are computed

Defending the Scanner Itself

A scanner that fetches arbitrary URLs is a risk to the host, so the tool guards itself:

• SSRF protection (netguard): refuse private, loopback and cloud-metadata addresses (e.g. 169.254.169.254) unless explicitly allowed, and re-check after redirects and DNS resolution
• Rate limits per IP and per target, a concurrency cap and a bounded queue
• Public mode: Cloudflare Turnstile, restrictions and a minimal abuse log
• Privacy: logs never contain targets or findings; results vanish after the TTL
• Ownership first: strong disclaimers, and active tests planned behind an ownership check
• Keep SECURITY.md for reporting vulnerabilities in the tool itself

Testing and Delivery

• Unit tests for checks; end-to-end tests for Docker, public mode, load, quality and a "dogfood" scan of the project's own site
• A smoke script against the deployed instance
• CI runs the tests; a monitor workflow runs on a schedule to watch the live site (GitHub Actions)
• Container build (1. Docker) and --fail-on for use as a pipeline gate (CI-CD Pipelines)
• Designed with a spec, an architecture doc and a numbered implementation plan committed to the repo before the code, a workflow that suits agents (AI Agents and Workflows)

Using It Well

1. Run it against your own staging and production sites after each release
2. Treat "no findings" as "nothing found by these checks", not "secure"
3. Fix high-severity items first (exposed .env, missing HTTPS, dangling DNS)
4. Add it to CI with --fail-on medium
5. Pair it with manual review, dependency scanning and a proper penetration test

Related: Network Security, Server Hardening with SSH, UFW and Fail2ban, Network Device Monitoring with NetPulse