pip install "web-posture-check[dns]"
web-posture-check example.com

Target: https://example.com (HTTP 200)
Score: 55/100 (grade F)
  [PASS] http-status: final response is HTTP 200
  [FAIL] hsts: Strict-Transport-Security header is missing
  [FAIL] csp: Content-Security-Policy header is missing
  ...
  [FAIL] tls-protocols: server accepts TLS 1.0, TLS 1.1, which are deprecated (RFC 8996)
  [WARN] caa: no CAA record, so any certificate authority may issue certificates for this host
  ...
  [FAIL] https-redirect: http://example.com/ is served over plain HTTP without redirecting to HTTPS

Why web-posture-check

• 20 checks in one run, covering the response, the TLS server and the domain's DNS: what a browser, a mail server and an attacker each see from outside. All checks.
• No false passes. When a check cannot decide (a DNS lookup failed, the local OpenSSL cannot offer TLS 1.0, a DKIM selector cannot be guessed), it says so as a WARN instead of passing.
• Grounded in the standards. Rules follow the RFCs, the Fetch standard and OWASP guidance, and each finding explains why it matters.
• Built for CI. Exit codes, --fail-on warn, JSON and Markdown reports, a score and grade, and a ready-made GitHub Action.
• Light. The core has no third-party dependencies; DNS checks use the optional [dns] extra. Python 3.9 or newer.

Contents

• Install
• Usage
• Checks
• Reports, score and exit codes
• GitHub Action
• How it works
• Development
• Releases · Contributing and security · Authors · License

Install

pip install web-posture-check            # headers, cookies, CORS, TLS, security.txt, HTTPS redirect
pip install "web-posture-check[dns]"     # also CAA, SPF, DMARC and DKIM (adds dnspython)

Without the [dns] extra the DNS checks are reported as skipped, not failed. To install from source, clone the repository and run pip install ".[dns]".

Usage

web-posture-check example.com                                 # every check, text report
web-posture-check https://example.com/login --json            # a specific page, JSON
web-posture-check example.com --format markdown --output report.md
web-posture-check site-one.com site-two.com --targets-file clients.txt --jobs 8
web-posture-check example.com --only tls-certificate,tls-protocols,caa
web-posture-check example.com --skip spf,dmarc,dkim --fail-on warn
web-posture-check --list-checks

Checks

web-posture-check --list-checks prints this list. Each check reports PASS, WARN or FAIL with a one-line reason.

Reports, score and exit codes

Formats. text (default) prints one line per finding. json gives url, status, findings, score and grade (plus note when checks were skipped or ran with --insecure); several targets give {"results": [...]}. markdown is a report for tickets, pull requests and emails, with failures first:

## Web posture report: https://example.com

HTTP 200, generated 2026-10-10 15:50 UTC by web-posture-check 0.3.0

**Grade F** (40/100): **3 FAIL**, **0 WARN**, 2 PASS

| Status | Check | Detail |
|---|---|---|
| FAIL | `hsts` | Strict-Transport-Security header is missing |
| FAIL | `csp` | Content-Security-Policy header is missing |
| FAIL | `https-redirect` | http://example.com/ is served over plain HTTP without redirecting to HTTPS |
| PASS | `http-status` | final response is HTTP 200 |
| PASS | `tls-certificate` | certificate valid until 2026-12-25 (76 days) |

Score and grade. Each check counts 1 for PASS, 0.5 for WARN and 0 for FAIL, averaged to 100, so it means the same for any --only / --skip selection. A is 90 and above, B 80, C 70, D 60, F below. A needs zero FAILs: one serious problem cannot hide behind many passes. Skipped checks are shown but not scored.

Exit codes. With several targets, the worst one wins.

GitHub Action

Check sites on a schedule. The job fails on problems and the Markdown report appears in the job summary.

name: Website posture
on:
  schedule:
    - cron: "0 6 * * 1"   # Mondays 06:00 UTC
  workflow_dispatch:

jobs:
  posture:
    runs-on: ubuntu-latest
    steps:
      - id: posture
        uses: MohammadThabetHassan/web-posture-check@v0.3.0
        with:
          targets: |
            example.com
            shop.example.com
          args: --fail-on warn
      - if: always()
        env:
          GRADE: ${{ steps.posture.outputs.grade }}
          SCORE: ${{ steps.posture.outputs.score }}
        run: echo "Grade $GRADE ($SCORE/100)"

For a fully reproducible workflow, pin the action to the release's commit SHA instead of the tag. The SecuritySolution.tech website runs this action every day alongside its own posture script.

How it works

• The response. The target is fetched once (redirects followed) and the headers, cookies and status of the final response are checked. A second request with Origin: https://web-posture-check.invalid, a reserved domain that cannot exist (RFC 2606), tests CORS: a site that trusts it trusts any website.
• TLS. The certificate is read with the standard verifying TLS context. TLS 1.0 and 1.1 are each probed with a handshake allowed only that version; OpenSSL 3 will not offer them at its default security level, so the probe lowers it for that connection only, and if it still cannot offer one the result is a WARN, never a pass.
• DNS. CAA is read for the host, climbing to parent domains as certificate authorities do (RFC 8659). SPF, DMARC and DKIM are read for the mail domain (www. removed); DMARC falls back to the organizational domain as receivers do; DKIM is looked up at <selector>._domainkey.<domain> for Google Workspace, Microsoft 365, Mailchimp, SendGrid, Cloudflare Email Routing and common defaults, or for --dkim-selector.
• Transport. The same host and path are requested over http:// (default port for an https:// target, the target's own port for an http:// one) to see whether it ends up on HTTPS.
• Concurrency and --insecure. Targets are scanned in a thread pool. A target scanned with --insecure gets its own unverified TLS context passed down its call chain only, so it can never affect another target's requests.

Development

pip install -e ".[dns,dev]"
python -m unittest discover -s tests -v
ruff check src tests

Checks are pure functions that take a response and return a Finding, so most tests need no network. tests/test_end_to_end.py runs the real CLI against small web servers on 127.0.0.1. CI lints with Ruff, runs the suite on Python 3.9, 3.11 and 3.13, and runs the GitHub Action from the checkout, including a case that must fail. Dependabot keeps the SHA-pinned actions and the Python tooling current.

Releases

Changes are listed in CHANGELOG.md. Pushing a tag such as v0.3.0 runs release.yml: it checks the tag matches the package version, builds and checks the package, and publishes it to PyPI with Trusted Publishing, so no PyPI token exists anywhere. Every published file carries a PyPI attestation linking it to that workflow.

Contributing and security

Contributions are welcome; see CONTRIBUTING.md. To report a vulnerability in the tool itself, follow SECURITY.md instead of opening a public issue.

Authors

• Mohammad Thabet (@MohammadThabetHassan)
• Omar Alraas (@omaralraas)

Most changes are pull requests that both authors work on, so each is co-authored by both.

License

MIT, see LICENSE.