QWED Infra guards for infrastructure verification

qwed-infra provides four guards to verify different aspects of your infrastructure. Every guard’s to_diagnostic() method converts its result into a unified InfraDiagnosticResult with an audit trace and proof reference. As of v0.3.0, every guard also exposes a to_verification_context() method that runs the verification and emits a portable Verification Context v1.0 document.

1. IamGuard

Engine: Z3 Theorem Prover IamGuard converts AWS IAM Policies into first-order logic formulas to prove or disprove access. This is superior to regex-based policy checks because it reasons about logic (AND, OR, NOT, Conditions) using an SMT solver.

Capabilities

Wildcard Logic: Correctly handles s3:*, bucket/* expansion using Z3 regex (InRe).
Conditions: Supports context keys like aws:SourceIp (CIDR blocks), aws:CurrentTime (Date comparisons), StringEquals, and StringLike.
Deny Overrides: Mathematically proves that an explicit Deny always overrides an Allow, regardless of statement order.
Least Privilege Analysis: verify_least_privilege(policy) proves whether a policy allows full admin access (* on *).
Unknown Operator Fail-Closed: An unrecognized condition operator causes a BLOCKED result — never a silent pass.

API

guard = IamGuard()
result = guard.verify_access(policy, action="s3:GetObject", resource="*", context={})
result = guard.verify_least_privilege(policy)
diag = IamGuard.to_diagnostic(result, audit_trace=None)

# Verification Context v1.0 — the guard runs verify_access() internally
doc = guard.to_verification_context(
    policy,
    action="s3:GetObject",
    resource="arn:aws:s3:::bucket/*",
    context={"aws:SourceIp": "192.168.1.5"},
    formal_statement="IAM policy is safe to apply",
    attestation_token=attestation.token,  # optional — mint and check `is_issued` first; see "Attestation trust boundary" below
)

Diagnostic Mapping

VerificationResult state	InfraDiagnosticStatus	proof_ref
`verified=True, allowed=True/False`	`VERIFIED`	`sha256:...`
`verified=False`	`UNVERIFIABLE`	`None`
Unknown operator / exception	`BLOCKED`	`None`

2. NetworkGuard

Engine: NetworkX (Graph Theory) NetworkGuard builds a directed graph of your network topology (VPCs, Subnets, Route Tables, Security Groups, NACLs, Internet Gateways). It uses graph traversal algorithms to verify reachability.

Capabilities

Public Access Check: Validates if a path exists from Internet to a specific Instance.
- Path: Internet -> IGW -> Route Table -> Subnet -> Security Group -> Instance.
Port Verification: Ensures critical management ports (22 SSH, 3389 RDP) are not exposed to 0.0.0.0/0.
Segmentation Verification: Proves that sensitive subnets (e.g., Database) are isolated from public subnets.
Fail-Closed Topologies: Returns UNVERIFIABLE when the topology contains NAT Gateways, VPC Peering, NACLs, or Transit Gateway — constructs the guard cannot model deterministically.

API

guard = NetworkGuard()
guard.build_graph(resources)  # Build NetworkX digraph from infra definition
result = guard.verify_reachability(resources, source="internet", destination="public-subnet", port=80)
diag = NetworkGuard.to_diagnostic(result)

# Verification Context v1.0 — the guard runs verify_reachability() internally
doc = guard.to_verification_context(
    resources,
    "internet",
    "public-subnet",
    80,
    formal_statement="Traffic from internet to public-subnet on port 80 is safe",
    attestation_token=attestation.token,  # optional — mint and check `is_issued` first; see "Attestation trust boundary" below
)

Malformed topology inputs (non-dict resources, subnets missing id keys, and similar) map to a fail-closed BLOCKED document instead of raising an exception.

Diagnostic Mapping

ComputedPath state	InfraDiagnosticStatus	proof_ref
`reachable=True`	`VERIFIED`	`sha256:...`
`unsupported_topology=True`	`UNVERIFIABLE`	`None`
`reachable=False` (with failure_code)	`BLOCKED`	`None`

3. CostGuard

Engine: Deterministic Arithmetic & Pricing Catalog CostGuard estimates the monthly cost of your infrastructure definition before deployment using an embedded, static pricing catalog with Decimal arithmetic (no floating-point rounding errors).

Capabilities

Budget enforcement: Blocks deployment if estimated_cost > budget.
Anomaly detection: Flags expensive instance types (e.g., p4d.24xlarge GPU instances) as suspected hallucinations.
Granular breakdown: Provides cost breakdown by resource type (Compute, Storage, Database).
Fail-Closed Unknown Types: Unknown instance or volume types produce a BLOCKED result — never a silent zero-cost estimate.

API

guard = CostGuard()
result = guard.verify_budget(resources, budget_monthly=500.0)
diag = CostGuard.to_diagnostic(result)

# Verification Context v1.0 — the guard runs verify_budget() internally
doc = guard.to_verification_context(
    resources,
    budget_monthly=500.0,
    formal_statement="Estimated monthly cost is within budget",
    attestation_token=attestation.token,  # optional — mint and check `is_issued` first; see "Attestation trust boundary" below
)

Malformed inputs (an undecimal budget, non-dict resources, non-dict resource entries) map to a fail-closed BLOCKED document instead of raising an exception.

Diagnostic Mapping

CostEstimate state	InfraDiagnosticStatus	proof_ref
`within_budget=True, has_unknown_types=False`	`VERIFIED`	`sha256:...`
`within_budget=False`	`BLOCKED`	`None`
`has_unknown_types=True`	`BLOCKED`	`None`
Cost parse error	`BLOCKED`	`None`

4. ArtifactBoundaryGuard

Engine: File system scanning + TOML build config validation ArtifactBoundaryGuard is a release gate that verifies a Python package’s source tree and pyproject.toml build configuration before publishing. It ensures that no secrets, debug artifacts, or unintended files leak into the distribution.

Capabilities

Secret Detection: Scans for .pem, .key, .env, credential files, and other sensitive patterns in the package surface.
Debug Artifact Detection: Flags test files (test_*.py), notebooks (*.ipynb), and debug directories (__pycache__, .git) included in the package.
Build Config Validation: Parses [tool.hatch.build.targets.wheel] to confirm the package boundary is explicit. Blocks if the config is missing, invalid, or doesn’t reference the expected package name.
Disclosure Risk Detection: Flags project-structure files (.gitignore, .dockerignore) that could leak internal conventions.
Fail-Closed on Missing TOML Parser: If neither tomllib nor tomli is available, every package is BLOCKED.

API

guard = ArtifactBoundaryGuard()
result = guard.verify_package_boundary(
    package_dir=Path("./src/mypackage"),
    pyproject_path=Path("./pyproject.toml"),
    package_name="mypackage",
)
diag = ArtifactBoundaryGuard.to_diagnostic(result)

# Verification Context v1.0 — the guard runs verify_package_boundary() internally
doc = guard.to_verification_context(
    package_dir="src/mypackage",
    pyproject_path="pyproject.toml",
    formal_statement="Package boundary is safe to publish",
    attestation_token=attestation.token,  # optional — mint and check `is_issued` first; see "Attestation trust boundary" below
)

The package identity is derived from the inspected package_dir, so a caller cannot scan one directory while checking the wheel configuration of another. Symlink escapes, symlink loops, non-string build backends, and wheel entries outside the scanned boundary map to a fail-closed BLOCKED document.

Diagnostic Mapping

ArtifactBoundaryResult state	InfraDiagnosticStatus	proof_ref
`is_safe=True`	`VERIFIED`	`sha256:...`
`is_safe=False` (with BLOCK-severity findings)	`BLOCKED`	`None`

Verification Context documents

Every guard’s to_verification_context() method returns a VerificationContextDocument: a portable, JSON-serializable trust artifact that records what was verified, by whom, with what proof, and whether a downstream system should admit or deny. Use it when a verification decision has to travel beyond your process: CI/CD gates, release pipelines, and audit logs.

Guards compute from raw inputs

to_verification_context() takes raw verification inputs, never a pre-computed result object. Each guard runs its own deterministic solver internally before emitting the document. A result-accepting signature would be forgeable: a caller could fabricate a positive result and mint an ADMIT decision. formal_statement is keyword-only and required on every guard:

IamGuard().to_verification_context(policy, action, resource, context=None,
                                   formal_statement="IAM policy is safe to apply")
NetworkGuard().to_verification_context(resources, source, destination, port,
                                       formal_statement="Traffic path is safe")
CostGuard().to_verification_context(resources, budget_monthly,
                                    formal_statement="Estimated cost is within budget")
ArtifactBoundaryGuard().to_verification_context(package_dir="mypkg", pyproject_path="pyproject.toml",
                                                formal_statement="Package boundary is safe to publish")

Breaking change in v0.3.0 (pre-1.0 API). Earlier unreleased signatures that accepted result objects were removed. If you passed a VerificationResult, ComputedPath, CostEstimate, or ArtifactBoundaryResult into to_verification_context(), pass the raw inputs instead and let the guard verify them itself.

Attestation trust boundary

A VERIFIED result produces an ADMIT decision only when accompanied by a cryptographically valid ES256 (ECDSA P-256) JWT attestation. Validation checks the signature, issuer, expiry, and revocation status, plus binding to the exact claim and evidence: the token’s status must match, its query_hash must equal sha256(formal_statement), and its proof_hash must equal the diagnostic’s proof_ref. A token minted for one statement can never admit a different one. Arbitrary non-empty attestation strings no longer grant ADMIT. They are rejected as forged tokens and produce BLOCKED. Mint a valid token with mint_diagnostic_attestation(), which binds the token to a VERIFIED diagnostic’s own evidence commitment:

from qwed_infra.attestation import mint_diagnostic_attestation

statement = "Traffic from internet to public-subnet on port 80 is safe"
diagnostic = NetworkGuard.to_diagnostic(
    net.verify_reachability(infra, "internet", "public-subnet", 80)
)
attestation = mint_diagnostic_attestation(
    diagnostic, engine="NetworkGuard", query=statement
)
if not attestation.is_issued:
    # Fail-closed contract: never proceed on an unissued attestation
    raise RuntimeError(f"Attestation unavailable [{attestation.error_code}]")

doc = net.to_verification_context(
    infra, "internet", "public-subnet", 80,
    formal_statement=statement,
    attestation_token=attestation.token,
)
print(doc.verdict.value)                     # VERIFIED / UNVERIFIABLE / BLOCKED
print(doc.context.decision.admission.value)  # ADMIT / DENY

mint_diagnostic_attestation() and the lower-level create_verification_attestation() return an AttestationResult, never None. Check .is_issued before using .token: BLOCKED means signing failed, UNVERIFIABLE means the cryptography/pyjwt packages are unavailable. Attestations are self-signed by the guard process with an ephemeral key and validated at the admission boundary. Multi-replica deployments require shared signing keys.

Verdict and admission mapping

The document is fail-closed by construction: anything that is not proven is DENY.

Diagnostic status	Attestation token	Document verdict	Admission
`VERIFIED`	Valid and bound to the claim and evidence	`VERIFIED`	`ADMIT`
`VERIFIED`	Missing (`None`)	`UNVERIFIABLE`	`DENY`
`VERIFIED`	Forged, expired, revoked, or bound to a different claim	`BLOCKED`	`DENY`
`UNVERIFIABLE`	Ignored	`UNVERIFIABLE`	`DENY`
`BLOCKED`	Ignored	`BLOCKED`	`DENY`

Malformed inputs at any VC boundary (invalid status values, non-dict developer fields, malformed topology, policy, budget, or package inputs) also map to BLOCKED/DENY documents instead of exceptions.

QWED Finance

QWED Legal

QWED Tax

QWED Infra

QWED Infra guards for infrastructure verification

1. IamGuard

Capabilities

API

Diagnostic Mapping

2. NetworkGuard

Capabilities

API

Diagnostic Mapping

3. CostGuard

Capabilities

API

Diagnostic Mapping

4. ArtifactBoundaryGuard

Capabilities

API

Diagnostic Mapping

Verification Context documents

Guards compute from raw inputs

Attestation trust boundary

Verdict and admission mapping

​1. IamGuard

​Capabilities

​API

​Diagnostic Mapping

​2. NetworkGuard

​Capabilities

​API

​Diagnostic Mapping

​3. CostGuard

​Capabilities

​API

​Diagnostic Mapping

​4. ArtifactBoundaryGuard

​Capabilities

​API

​Diagnostic Mapping

​Verification Context documents

​Guards compute from raw inputs

​Attestation trust boundary

​Verdict and admission mapping

1. IamGuard

Capabilities

API

Diagnostic Mapping

2. NetworkGuard

Capabilities

API

Diagnostic Mapping

3. CostGuard

Capabilities

API

Diagnostic Mapping

4. ArtifactBoundaryGuard

Capabilities

API

Diagnostic Mapping

Verification Context documents

Guards compute from raw inputs

Attestation trust boundary

Verdict and admission mapping