webconf-audit 0.1.1__tar.gz

webconf_audit-0.1.1/.gitignore

@@ -0,0 +1,27 @@
+# Python
+__pycache__/
+*.pyc
+src/*.egg-info/
+
+# Virtual environments
+.venv/
+
+# Tooling caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# Editors and IDEs
+.vscode/
+
+# Local working directory and generated reports
+/.lab/
+/.tmp/
+/.codex-tmp/
+/.codex-docx-render*/
+/tmpkd_ok9wt/
+/demo/local_admin/reports/
+
+# Office documents and temp files
+/*.docx
+/~$*.docx

webconf_audit-0.1.1/CHANGELOG.md

@@ -0,0 +1,85 @@
+# Changelog
+
+All notable project changes are recorded here.
+
+This project is still in the pre-1.0 stage. Public releases use `vX.Y.Z` Git
+tags, and each released version must have a matching section in this file before
+release artifacts are prepared.
+
+## [Unreleased]
+
+## [0.1.1] - 2026-06-16
+
+- Add a schema-versioned packaged control-source coverage ledger, strict
+  registry reconciliation, deterministic Markdown/JSON views, additive
+  `coverage validate/show/export` commands, and release checks for document
+  and package-artifact drift without increasing any coverage numerator.
+- Add deterministic offline crosswalk validation, canonical OWASP/ASVS/PCI
+  identifiers, and declared-versus-derived provenance in rule catalog and
+  report JSON; conservatively correct ASVS, OWASP Top 10:2025, and PCI DSS
+  coverage claims without changing detector behavior.
+- Expand OpenAPI / Swagger external probes with common JSON schema paths and
+  map Swagger/OpenAPI exposure to ASVS v5.0.0-13.4.5 partial documentation
+  endpoint coverage.
+- Expand dependency-manifest external probes with Java Maven/Gradle and
+  .NET/NuGet manifest paths, and map the rule to ASVS v5.0.0-13.4.6 partial
+  version-disclosure coverage.
+- Add exposed Nginx, Apache HTTP Server, and Lighttpd configuration-file
+  probes to the external safe-probe catalog.
+- Add policy-gated `nginx.response_headers` control assessments with shared
+  Nginx `add_header` / `add_header_inherit` semantics, a structured CSP AST,
+  and route-manifest evaluation for CSP, Referrer-Policy, HSTS,
+  `X-Content-Type-Options`, and COOP without changing canonical coverage
+  percentages.
+- Add declared endpoint/SNI TLS inventory analysis with a dedicated
+  `analyze-tls-inventory` command, typed `external.tls_inventories` policy
+  input, bounded TLS observation records, and follow-up-04-compatible native
+  control assessment evidence without changing canonical coverage percentages.
+- Correct the reviewed no-policy Nginx header edge cases called out by the
+  follow-up design: location or `if in location` header replacement can now
+  surface a missing CSP that was previously hidden, report-only CSP does not
+  satisfy enforcement, and multiple enforcing CSP headers use conjunction
+  semantics for unsafe-inline / unsafe-eval checks.
+- Add application settings JSON exposure probes to the external safe-probe
+  catalog.
+- Document the TLS source-coverage explanation across NIST, PCI DSS, ISO/IEC
+  27002, and FSTEC mappings.
+- Add JavaScript source map exposure probes to the external safe-probe catalog.
+- Expand dependency-manifest external probes with Python, Ruby, Go, and Rust
+  project manifest and lockfile paths.
+- Rework the project roadmap around source coverage from the pre-diploma
+  benchmark and relevance sources.
+- Expand the external safe-probe catalog with additional environment-file,
+  database-dump, dependency-manifest, and archive path variants for existing
+  catalog-backed rules.
+- Document the standards-mapping health snapshot after the `v0.1.0` tag and
+  pin the remaining mapping backlog to safe-probe catalog growth.
+- Continue parser/effective-configuration precision work for the current
+  four-server scope.
+- Continue standards mapping, safe external probe growth, report explanation
+  improvements, and release-readiness work.
+
+## [0.1.0] - 2026-06-05
+
+### Added
+
+- Local static analyzers for Nginx, Apache HTTP Server, Lighttpd, and Microsoft
+  IIS.
+- External safe probing for HTTP, HTTPS, TLS, certificate, redirect, cookie,
+  CORS, method, fingerprinting, and sensitive-path observations.
+- Central rule registry with `list-rules`, rule metadata, standards mapping,
+  and profile-based severity calibration.
+- Text and JSON reports with stable finding fingerprints, standards grouping,
+  and repeated-finding grouping.
+- CI-oriented exit behavior through `--fail-on` and `--fail-on-new`.
+- Suppression files with required reasons and expiry dates.
+- Baseline creation and diff reporting for new, unchanged, resolved, and
+  suppressed findings.
+- Repository CI, optional Docker-backed integration checks, and a repeatable
+  release check that builds and smoke-tests installed package artifacts.
+
+### Documented
+
+- Current project status, architecture, roadmap, severity methodology,
+  standards coverage, CI integration, real-world-style fixture testing, and
+  release preparation boundaries.

webconf_audit-0.1.1/PKG-INFO

@@ -0,0 +1,12 @@
+Metadata-Version: 2.4
+Name: webconf-audit
+Version: 0.1.1
+Summary: Web server configuration security audit tool
+Requires-Python: >=3.10
+Requires-Dist: click<9.0,>=8.1
+Requires-Dist: cryptography<47,>=46.0.7
+Requires-Dist: defusedxml<1.0,>=0.7
+Requires-Dist: pydantic<3.0,>=2.12.5
+Requires-Dist: pyopenssl<27,>=26.0.0
+Requires-Dist: pyyaml<7,>=6.0.3
+Requires-Dist: typer<1.0,>=0.24.1

webconf_audit-0.1.1/README.md

@@ -0,0 +1,420 @@
+# webconf-audit
+
+A security auditing tool for web server configurations.
+
+`webconf-audit` has two independent analysis modes:
+
+- **Local** — static analysis of configuration files on the host that
+  runs the web server.
+- **External** — black-box probing of a running web endpoint over the
+  network using observable HTTP, HTTPS, and TLS signals.
+
+## Supported servers
+
+Local analysis covers four web servers:
+
+- Nginx
+- Apache HTTP Server
+- Lighttpd
+- Microsoft IIS
+
+External probing is server-agnostic; a few checks are activated only
+after fingerprinting identifies the underlying server (for example,
+Apache `mod_status` exposure or IIS detailed error pages).
+
+## Installation
+
+`webconf-audit` requires Python 3.10 or later.
+
+```bash
+pip install .
+```
+
+The package exposes a `webconf-audit` console entry point. Every
+command is also available via `python -m webconf_audit.cli`.
+
+## Quick start
+
+### Local analysis
+
+```bash
+webconf-audit analyze-nginx /etc/nginx/nginx.conf
+webconf-audit analyze-apache /etc/apache2/httpd.conf
+webconf-audit analyze-lighttpd /etc/lighttpd/lighttpd.conf
+webconf-audit analyze-iis C:\inetpub\wwwroot\web.config
+webconf-audit analyze-iis C:\inetpub\wwwroot\web.config --tls-registry schannel.json
+```
+
+### External analysis
+
+```bash
+webconf-audit analyze-external https://example.com
+webconf-audit analyze-external example.com --ports 80,443,8443
+webconf-audit analyze-external example.com --no-scan-ports
+```
+
+### Output formats
+
+Every `analyze-*` command supports text (default) and JSON output:
+
+```bash
+webconf-audit analyze-nginx config.conf --format json
+webconf-audit analyze-external example.com -f json
+webconf-audit analyze-nginx config.conf --group-by standard
+webconf-audit analyze-nginx config.conf --group-repeated
+```
+
+The JSON envelope contains a generation timestamp, a summary, the
+per-target results, the deduplicated findings list, repeated finding groups
+under `finding_groups`, standards references under each finding and the
+top-level `standards` summary, and the issues list. Schema version 1 also
+adds top-level `schema_version` and `generator` fields so downstream tooling
+can verify the report format, generator package name and version, and registry
+revision. See [docs/report-format.md](docs/report-format.md) for the full JSON
+contract.
+
+When an explicit policy is supplied, JSON results also include additive
+`result.metadata.audit_policy` and `result.metadata.rule_execution` entries.
+See [docs/audit-policy.md](docs/audit-policy.md) and
+[docs/report-format.md](docs/report-format.md).
+
+Use `--group-repeated` with text output to collapse repeated findings that
+share the same rule, severity, recommendation, and report grouping cause while
+preserving each exact source location.
+
+Use `--group-by standard` with text output to review findings by mapped
+standards such as CWE, OWASP Top 10, and OWASP ASVS. Findings with no mapped
+standard are grouped under `Unmapped`.
+
+### CI gating
+
+Every `analyze-*` command can act as a CI gate with `--fail-on`:
+
+```bash
+webconf-audit analyze-nginx nginx.conf --fail-on medium
+webconf-audit analyze-external example.com --fail-on high --format json
+```
+
+Exit codes in CI-gating mode:
+
+- `0` - analysis completed and no findings at or above the selected severity
+  were found.
+- `1` - analysis produced an execution or configuration error.
+- `2` - analysis completed and at least one finding met the selected severity
+  threshold.
+
+JSON findings include a stable `fingerprint` field that is designed for CI,
+suppressions, and baseline/diff reporting.
+
+When `--fail-on` is used, `.webconf-audit-ignore.yml` is read from the current
+working directory if it exists. Suppressions require `rule_id`, either a
+`fingerprint` or locator fields, a human-readable `reason`, and an `expires`
+date. Expired suppressions stop hiding findings and are reported as analysis
+issues.
+
+```yaml
+suppressions:
+  - rule_id: nginx.server_tokens_on
+    source: nginx.conf
+    line: 12
+    reason: Accepted for staging until the shared image is rebuilt.
+    expires: 2026-12-31
+```
+
+Use `--suppressions <path>` to point at a non-default suppression file. Full CI
+examples are available in [docs/ci-integration.md](docs/ci-integration.md).
+
+### Baseline and diff mode
+
+Use `--write-baseline` to capture the current accepted finding set:
+
+```bash
+webconf-audit analyze-nginx nginx.conf --write-baseline webconf-audit-baseline.json
+```
+
+Use `--baseline` to compare a later run against that known state. Text output
+shows a short diff summary, and JSON output includes `new_findings`,
+`unchanged_findings`, `resolved_findings`, and `suppressed_findings`.
+
+```bash
+webconf-audit analyze-nginx nginx.conf --baseline webconf-audit-baseline.json
+```
+
+CI can block only new debt with `--fail-on-new` while leaving existing baseline
+findings unchanged:
+
+```bash
+webconf-audit analyze-nginx nginx.conf --baseline webconf-audit-baseline.json --fail-on-new medium
+```
+
+### Explicit audit policy
+
+Policies are always opt-in and must be passed explicitly:
+
+```bash
+webconf-audit policy validate --policy .webconf-audit-policy.yml
+webconf-audit policy show --policy .webconf-audit-policy.yml --mode local --server-type nginx --target /etc/nginx/nginx.conf
+webconf-audit analyze-nginx /etc/nginx/nginx.conf --policy .webconf-audit-policy.yml
+```
+
+Policies request evidence review scope and opt-in rule tags, but they do not
+hide findings or raise coverage percentages by themselves.
+
+### Control assessment
+
+Assessment is a separate step that consumes a versioned analysis report with
+embedded resolved policy and rule-execution metadata:
+
+```bash
+webconf-audit analyze-nginx nginx.conf --policy .webconf-audit-policy.yml --format json > analysis.json
+webconf-audit assess --report analysis.json
+webconf-audit assess --report analysis.json --format json
+webconf-audit assess --report analysis.json --fail-on fail,indeterminate
+```
+
+`assess` produces a conservative evidence report for resolved policy controls.
+It does not emit a compliance percentage or certification claim, and a
+zero-finding run does not automatically become `pass`.
+
+Assessment exit codes:
+
+- `0` - assessment was produced and no requested gate status was present.
+- `1` - the report, ledger, policy verification, or output path could not be
+  trusted.
+- `2` - invalid CLI usage.
+- `3` - assessment was produced successfully and a requested `--fail-on`
+  status was present.
+
+Use `--policy` with `assess` only to verify that the supplied policy resolves
+to the same embedded hashes as the original analysis report. See
+[docs/control-assessment.md](docs/control-assessment.md).
+
+## Local analysis pipeline
+
+Each local analyzer:
+
+1. Reads the main configuration file passed on the command line.
+2. Resolves includes or rebuilds the inheritance chain.
+3. Builds an effective configuration where the server model
+   requires it.
+4. Runs server-specific rules over the parsed/effective form.
+5. Runs universal rules over a normalized representation shared by
+   all four servers.
+6. Returns a structured result with findings, technical issues, and
+   source metadata.
+
+What each analyzer handles:
+
+- **Nginx** — tokenizer, parser, `include` resolution with glob
+  support and cycle detection, AST traversal, source-location
+  tracking on every directive.
+- **Apache** — `Include` and `IncludeOptional` resolution,
+  `.htaccess` discovery from `Directory` blocks and `DocumentRoot`,
+  `AllowOverride` filtering, per-`VirtualHost` analysis contexts,
+  `Location` and `LocationMatch` layering, header merge semantics.
+- **Lighttpd** — variable expansion, `include` resolution,
+  `include_shell` handling (skipped with a warning by default, with
+  explicit opt-in execution via `--execute-shell`),
+  conditional blocks such as `$HTTP["host"] == "..."`, optional
+  per-host targeted analysis via `--host`.
+- **IIS** — safe XML parsing through `defusedxml`, three-level
+  inheritance chain `machine.config` → `applicationHost.config`
+  → `web.config`, `<add>` / `<remove>` / `<clear>` collection
+  semantics, `<location>` inheritance, `--machine-config` option for
+  explicit base config selection, and Windows SChannel TLS registry
+  enrichment by default on Windows hosts. Use `--tls-registry <path>`
+  for a JSON export from the target IIS server or `--no-tls-registry`
+  to disable live registry enrichment.
+
+Each finding records severity, description, remediation hint, and a
+source reference: file and line for text configurations, file and XML
+path for IIS, observable endpoint or header for external mode.
+
+## External analysis
+
+External mode probes a target without access to its configuration. It
+performs:
+
+- Port discovery for bare-host targets (default ports: 80, 443, 8080,
+  8443, 8000, 8888, 3000, 5000, 9443; can be overridden with
+  `--ports` or disabled with `--no-scan-ports`).
+- HTTP and HTTPS probing with `HEAD` → `GET` fallback plus a separate
+  `OPTIONS` flow.
+- TLS enrichment: negotiated protocol and cipher, supported TLS
+  versions, certificate chain completeness, SAN extraction.
+- Server fingerprinting from response headers, default error pages,
+  and reactions to deliberately malformed requests.
+- Sensitive-path probing for paths such as `/.git/HEAD`, `/.env`,
+  `/.htaccess`, `/phpinfo.php`, `/web.config`, `/robots.txt`,
+  `/sitemap.xml`.
+- Redirect chain analysis: loops, scheme switches, off-domain hops.
+
+External rules cover HTTPS availability and HSTS, common security
+headers, server identification, cookies, CORS, HTTP methods,
+sensitive paths, TLS protocol versions, and certificate validity.
+
+## Rule catalog
+
+The rule catalog is browsable through the CLI:
+
+```bash
+webconf-audit list-rules
+webconf-audit list-rules --category local --server-type nginx
+webconf-audit list-rules --severity high --tag tls
+webconf-audit list-rules --format json
+```
+
+Filters: `--category` (`local`, `external`, `universal`),
+`--server-type` (`nginx`, `apache`, `lighttpd`, `iis`),
+`--severity` (`critical`, `high`, `medium`, `low`, `info`),
+`--tag`.
+
+Use `--format json` to get a machine-readable inventory with the full
+`RuleMeta` payload (rule_id, severity, category, server_type,
+input_kind, tags, severity_profile, standards, order, etc.). The full
+inventory and the standards mapping plan live in
+[docs/rule-coverage.md](docs/rule-coverage.md). Severity calibration is
+documented in [docs/severity-methodology.md](docs/severity-methodology.md).
+Each standard reference includes additive `origin` and `derived_from` fields,
+so independently reviewed mappings can be distinguished from automatic
+edition alignments.
+
+## Control-source coverage ledger
+
+The counted coverage snapshot is stored in the versioned package file
+`src/webconf_audit/data/control_source_coverage.yml`. It records stable source
+and item IDs, applicability, grouped requirements, evidence limitations,
+registry claims, exclusions, and review provenance. The ledger describes
+implemented scanner evidence within the documented scope; it is not a claim
+of certification or target compliance.
+
+Explicit audit policies are a separate layer on top of the ledger. They can
+select sources and request opt-in evidence, but they do not change the counted
+coverage snapshot on their own. Per-target status belongs to the separate
+assessment artifact, not to the coverage percentages shown here.
+
+Validate or inspect the shipped ledger with:
+
+```bash
+webconf-audit coverage validate
+webconf-audit coverage validate --format json
+webconf-audit coverage reconcile --check
+webconf-audit coverage reconcile --check --format json
+webconf-audit coverage reconcile --write
+webconf-audit coverage show --source owasp-asvs-5.0.0
+webconf-audit coverage show --status partial --format json
+webconf-audit coverage export --format markdown
+```
+
+Custom local ledgers can be supplied with `--ledger PATH`. Exports refuse to
+overwrite an existing file unless `--force` is given. The `reconcile`
+maintainer command checks or atomically rewrites the tracked coverage
+documents from the packaged ledger. The generated human-readable view remains available at
+[docs/control-source-coverage-tracker.md](docs/control-source-coverage-tracker.md);
+the methodology and headline summary are documented in
+[docs/benchmarks-covering.md](docs/benchmarks-covering.md).
+
+The catalog currently contains 473 rules:
+
+| Category | Rules |
+|----------|------:|
+| Local — Nginx | 96 |
+| Local — Apache | 88 |
+| Local — Lighttpd | 50 |
+| Local — IIS | 53 |
+| Universal (local) | 14 |
+| External | 172 |
+
+Ten rules in the inventory above are opt-in `policy-review` rules.
+They are excluded from default `analyze-*` runs and surfaced only when
+`--enable-policy-review` is passed. See
+[docs/rule-coverage.md](docs/rule-coverage.md#documented-scope-limits)
+for the rationale.
+
+## Reporting
+
+Results are aggregated into a `ReportData` structure with a summary by
+severity, analysis mode, server type, and mapped standards. Two output
+formatters are available:
+
+- `TextFormatter` — human-readable command-line output.
+- `JsonFormatter` — machine-readable output suitable for downstream
+  tooling.
+
+Universal rule findings are deduplicated when a more specific
+server-specific rule has already reported the same issue at the same
+location.
+
+## Project status
+
+The post-practice project baseline is recorded in
+[docs/project-status.md](docs/project-status.md). It summarizes the current
+implemented scope, validation status, known boundaries, and the next
+graduation-project work items.
+
+User-visible changes are tracked in [CHANGELOG.md](CHANGELOG.md). Release
+preparation, versioning, tag rules, and package smoke checks are documented in
+[docs/release.md](docs/release.md).
+
+## Demo
+
+A working local-analysis demo with reproducible Docker-based syntax
+checks is provided in `demo/local_admin/`. See
+[demo/local_admin/README.md](demo/local_admin/README.md) for the
+full walkthrough.
+
+A separate defensive validation dataset with public-source-derived config
+fixtures lives in [demo/real_world_configs/](demo/real_world_configs/).
+Security-focused known-bad/known-good fixture testing is documented in
+[docs/testing-real-world-configs.md](docs/testing-real-world-configs.md).
+
+## Roadmap
+
+The current development plan is tracked in
+[docs/roadmap.md](docs/roadmap.md).
+
+Near-term work is focused on parser/effective-configuration precision,
+standards-driven coverage, safe external probe growth, false-positive
+reduction, and release preparation. New server-family support should be planned
+separately after the current four-server core is stable.
+
+## Development
+
+Install the development dependency group:
+
+```bash
+uv sync --group dev --locked
+```
+
+Run the same fast checks as the pull-request CI workflow:
+
+```bash
+uv run --locked ruff check .
+uv run --locked python -m compileall -q src
+uv run --locked pytest tests --ignore=tests/integration_external --ignore=tests/integration_local --ignore=tests/integration_rule_coverage --ignore=tests/integration_real_world_cross_mode -q
+uv run --locked webconf-audit list-rules
+uv run --locked interrogate -c pyproject.toml
+```
+
+The `interrogate` check enforces a 40% docstring coverage floor over
+`src/` with sensible exclusions (private / dunder / nested helpers).
+The threshold reflects the project's "default to no comments, only
+explain non-obvious WHY" convention while still requiring docstrings
+on module entries, data models, and the public API surface.
+
+Run the Docker-backed integration slice when Docker Engine is available:
+
+```bash
+uv run --locked pytest tests/integration_external tests/integration_local tests/integration_rule_coverage -q
+```
+
+Run the release check before preparing a public package artifact:
+
+```bash
+uv run --locked python scripts/release_check.py
+```
+
+The release check builds wheel and source distribution artifacts, installs the
+wheel into a clean virtual environment, verifies the installed console entry
+point, and runs a small installed-package smoke test. See
+[docs/release.md](docs/release.md) for the full checklist.

webconf_audit-0.1.1/pyproject.toml

@@ -0,0 +1,88 @@
+[project]
+name = "webconf-audit"
+version = "0.1.1"
+description = "Web server configuration security audit tool"
+requires-python = ">=3.10"
+dependencies = [
+    # In the absence of a dedicated oldest-supported CI job, keep the
+    # lower bounds aligned with the dependency set exercised by the
+    # current test environment. Cap the next major so SemVer breakage
+    # does not silently land via a fresh `pip install`.
+    "click>=8.1,<9.0",
+    "defusedxml>=0.7,<1.0",
+    "cryptography>=46.0.7,<47",
+    "pydantic>=2.12.5,<3.0",
+    "pyOpenSSL>=26.0.0,<27",
+    "PyYAML>=6.0.3,<7",
+    "typer>=0.24.1,<1.0",
+]
+
+[project.scripts]
+webconf-audit = "webconf_audit.cli:app"
+
+[build-system]
+requires = ["hatchling>=1.28,<2"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/webconf_audit"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/src",
+    "/README.md",
+    "/CHANGELOG.md",
+    "/LICENSE",
+    "/pyproject.toml",
+    "/uv.lock",
+]
+
+[dependency-groups]
+dev = [
+    "interrogate>=1.7.0,<2",
+    "pytest>=9.0.3,<10",
+    "ruff>=0.15.12,<1",
+]
+
+[tool.ruff]
+line-length = 100
+exclude = [".tmp"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+cache_dir = ".tmp/pytest-cache"
+norecursedirs = [
+    ".git",
+    ".venv",
+    ".tmp",
+    "pytest-run-*",
+    "pytest-tmp-*",
+]
+
+# Docstring coverage. The 40% floor reflects the project convention
+# "Default to writing no comments. Only add one when the WHY is
+# non-obvious." Public API surfaces, data models, and module-level
+# docstrings are documented; small internal helpers with
+# self-documenting names are intentionally left bare. The exclusions
+# below skip categories where docstrings add noise rather than value
+# (private/dunder methods, nested helpers, overloaded stubs).
+[tool.interrogate]
+fail-under = 40
+ignore-init-method = true
+ignore-init-module = true
+ignore-magic = true
+ignore-private = true
+ignore-semiprivate = true
+ignore-nested-functions = true
+ignore-nested-classes = true
+ignore-overloaded-functions = true
+ignore-property-decorators = true
+ignore-property-setters = true
+exclude = [
+    "tests",
+    ".tmp",
+    ".venv",
+    ".codex-tmp",
+    ".codex-docx-render*",
+    "tmpkd_ok9wt",
+]