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 silent passes. When a check cannot decide (a DNS lookup failed, the local OpenSSL cannot offer TLS 1.0, a DKIM selector cannot be guessed, plain HTTP answered with something unreadable), it says so as a WARN instead of passing.
• Grounded in the standards. Rules follow the RFCs, the Fetch, HTML and CSP standards and OWASP guidance, and each finding explains why it matters. A repeated or comma-separated header is read the way browsers read it.
• Safe to point at a hostile site. It speaks only HTTP and HTTPS, refuses redirects to other schemes, and escapes what a site sends before printing it, so a report cannot drive your terminal or add links to a pull request.
• Built for CI. Exit codes, --fail-on warn, JSON, Markdown and SARIF reports, a score and grade, a ready-made GitHub Action, and findings in GitHub code scanning.
• 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 and code scanning
• How it works
• Compared with other tools · Compatibility
• 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 example.com --sarif posture.sarif               # text report plus a SARIF log
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. sarif is a SARIF 2.1.0 log for GitHub code scanning and other SARIF viewers. json gives url, status, findings, score and grade (plus note when checks were skipped or ran with --insecure); several targets give {"results": [...]}, in input order. A target that could not be scanned is still there, with "status": null, "findings": [] and an "error", so the output is always one valid JSON document. markdown is a report for tickets, pull requests and emails, with failures first; a target that could not be scanned gets an Error: line instead of a table. The URL and the details are code spans, so text a site sends is shown literally and cannot add links, images, HTML or @mentions:

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

HTTP 200, generated 2026-10-10 15:50 UTC by web-posture-check 0.4.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.4.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)"

GitHub code scanning

Since v0.4.0: upload the sarif output and every FAIL and WARN becomes an alert in the repository's Security tab. Alerts open when a problem appears and close by themselves when a later scan no longer finds it.

jobs:
  posture:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      security-events: write
    steps:
      - id: posture
        uses: MohammadThabetHassan/web-posture-check@v0.4.0
        with:
          targets: example.com
      - if: always() && steps.posture.outputs.sarif != ''
        uses: github/codeql-action/upload-sarif@v4
        with:
          sarif_file: ${{ steps.posture.outputs.sarif }}
          category: web-posture-check

FAIL becomes an error and WARN a warning; PASS and skipped checks are not uploaded. Each rule carries a security-severity, so GitHub shows alerts as High, Medium or Low: cors 8.0 and tls-certificate 7.5 are high; hsts and https-redirect 6.5, cookies 6.0, csp, tls-protocols and dmarc 5.5, spf 5.0 and clickjacking 4.5 are medium; the rest are low. They are defaults for each check's worst case, set in src/webposture/checks.py. If the repository's code scanning check fails only on High or higher, the medium rules no longer fail it; the Action step itself still fails on any FAIL. A website has no source line, so each alert points to the workflow file that ran the scan and names the URL in its message. An alert's identity is the check and the URL, so a detail that changes between runs (such as days until a certificate expires) updates the same alert instead of opening a new one. The Action's own CI uploads its SARIF to code scanning on every change, so the format is checked against GitHub itself, and validates it against the OASIS SARIF 2.1.0 schema.

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 and the headers and status of the final response are checked, with the cookies of every response on the way. Only http:// and https:// are ever requested: a redirect to anything else (file:, ftp:) is refused, as are redirect loops. 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, found with the Public Suffix List that ships with the package; SPF's DNS lookups are counted through its includes; 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. Its Strict-Transport-Security is judged as configured, with a note that browsers ignore it until the certificate is trusted.
• Output. Findings quote what a site sent. Text and Markdown reports show control characters (terminal escape sequences, bidirectional overrides) as visible escapes such as \x1b, and Markdown puts the quoted text in code spans. JSON and SARIF escape it as JSON does.

Compared with other tools

web-posture-check does not replace the established tools below; it puts a broad, standards-based baseline of all three areas (web, TLS, email DNS) into one command that fits a pipeline. Pick by the question you are asking:

A good pattern is to run web-posture-check on every change or on a schedule to catch regressions, and the specialist tools when you need depth in one area.

What web-posture-check does not do: test ciphers or TLS vulnerabilities (use testssl.sh); check DNSSEC, IPv6, DANE or mail-server STARTTLS (use internet.nl), or MTA-STS, which internet.nl does not test either; crawl a site or test for vulnerabilities such as XSS or SQL injection (use a scanner such as OWASP ZAP). It looks at one URL per target from outside, as a visitor, a mail receiver or an attacker would.

Compatibility

Version 0.x, but scripts and pipelines can rely on these. A change to any of them is listed in the CHANGELOG and only made in a new minor version (0.x to 0.y), never in a patch release:

• Exit codes 0, 1, 2 and 130 and what they mean.
• Check names (--list-checks), which are also the SARIF rule IDs and the names --only and --skip take. A new check can be added in a minor version; it is announced in the CHANGELOG, since --fail-on may then fail on it.
• JSON fields: url, status, findings (check, status, detail), score, grade, note, error for a target that could not be scanned, and results for several targets. New fields may be added.
• Statuses PASS, WARN and FAIL, and that a skipped check starts its detail with skipped:.
• Action inputs and outputs: the inputs targets, args, dns and python-version, and the outputs score, grade, exit-code, report and sarif.

The detail text, the text and Markdown layouts and the exact score of a site can change in any release: a check that becomes more accurate can change a result. Pin a version (web-posture-check==0.4.0, or the action at a release SHA) for fully repeatable results.

Development

pip install -e ".[dns,dev]"
coverage run tests/offline.py && coverage report   # every test, network blocked, branch coverage
ruff check src tests                                 # lint
mypy                                                 # strict for the package, tests included

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, tests/test_https_end_to_end.py does the same over HTTPS, and tests/test_tls_live.py runs real TLS handshakes; both use a throwaway CA made by openssl, so the certificate and protocol code is tested without mocks. No test touches the internet: tests/offline.py runs the suite with only loopback reachable and fails it if any test tries more.

CI on every change:

• Ruff lint and mypy, strict for the package and checking every function body of the tests.
• The test suite, with the network blocked, on Python 3.9 to 3.15 on Linux and on Windows and macOS. Branch coverage must stay at 99% or more (100% today); each Linux run puts the coverage table in its job summary.
• The built wheel and source archive, checked with twine and installed into clean environments with and without the [dns] extra.
• CodeQL static analysis of the Python code and the workflows (security-extended queries).
• The GitHub Action run from the checkout: a passing case, a case that must fail, and its SARIF uploaded to code scanning and validated against the OASIS schema.

Every action in the workflows is pinned to a commit SHA, no checkout keeps the job's token, and Dependabot keeps the actions and the Python tooling current, proposing a new release only after it has been out for a week.

Releases

Changes are listed in CHANGELOG.md. Pushing a tag such as v0.4.0 runs release.yml: it checks the tag matches the package version, runs the test suite, 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. The bundled Public Suffix List (src/webposture/public_suffix_list.dat) is from publicsuffix.org under the Mozilla Public License 2.0, as its header says, so the package's licence expression is MIT AND MPL-2.0.