snowfort-audit 1.0.1

Clean Architecture WAF auditor for Snowflake

Snowfort Audit: Snowflake WAF Scorecard

Snowfort Audit is a Policy-as-Code (PaC) and Well-Architected Framework (WAF) compliance tool for Snowflake. It audits your Snowflake environment against 116 deterministic rules across Security, Cost, Performance, Reliability, Operations, and Governance — through both static analysis and runtime inspection.

Key Concepts

1. Dual-Mode Inspection

• Offline Mode (--offline): Statically analyzes project files (manifest.yml, SQL scripts, Jinja) for configuration errors and best practice violations. No Snowflake connection required.
• Online Mode (Default): Connects to your live Snowflake account to inspect runtime configurations, usage history, object states, and tag compliance.

2. The WAF Scorecard

Every audit run generates a Snowarch WAF Scorecard, providing a 0-100 health score for each architectural pillar and an overall project grade (A–F). This output is designed for FinOps and Security team reviews.

3. Verification Gateway

Snowarch Audit acts as a deterministic verification layer: it reliably identifies WAF violations and remediation steps. Use it to validate that AI-generated or hand-written Snowflake code is safe, cost-efficient, and compliant—before or after deployment.

---

Rule Suite — 116 rules across 7 WAF-aligned categories

v0.4.0 adds 26 new rules: 18 Cortex AI cost governance rules (COST_016–033), 8 additional coverage rules (Dynamic Tables, Data Sharing, Permifrost drift, sandbox sprawl, cross-region inference), and 7 Q1 2026 feature rules (PAT governance, AI_REDACT, authorization policies, Trust Center, PrivateLink, SPCS, Iceberg).

Category	Rules	Key Checks
Cost Optimization	35	Zombie warehouses, auto-suspend, Cortex AI/Code/Agents/Search/Analyst cost governance, credit budgets, model allowlists, per-user quotas
Security	26	Admin exposure (graph reachability), MFA, network perimeter, PAT governance, AI_REDACT coverage, authorization policies, Trust Center, PrivateLink enforcement, SPCS security
Performance	15	Remote/local spillage, workload efficiency "Pincer", cache contention, query queuing, partition pruning, clustering quality, Dynamic Table lag, Gen2/Snowpark pivot
Operations	14	Resource monitors, mandatory tagging, IaC drift readiness, Permifrost spec drift, developer sandbox sprawl, alert configuration, observability infrastructure
Reliability	10	Replication gaps, retention safety, failover completeness, Dynamic Table refresh lag and failure detection
Governance	9	Future grants anti-pattern, object documentation, account budget, sensitive data classification, Iceberg governance, inbound/outbound share risk, cross-region inference
Static Analysis	7	Hardcoded secrets, naked DROP statements, SQL anti-patterns, MERGE pattern, Dynamic Table complexity

The full rule catalog with IDs, severities, and modes is in docs/RULES_CATALOG.md.

---

🛠 Usage

Quick start (online scan)

1. Install: pip install snowfort-audit (or pipx install snowfort-audit).
2. Run login with eval so env vars are set in your shell: eval $(snowfort login).
3. Run a scan: snowfort audit scan.

Installation

pip install snowfort-audit

For local development (editable install with dev extras), use a single spec so pip does not treat the package twice:

pip install -e ".[dev]"

Documentation: Severity & grading rubric — how scores and rule severities are determined.

Custom Rules (Extensibility)

You can extend snowfort-audit with your own custom rules by creating a Python package and registering it via entry points.

1. Create a package with your rule class (inheriting from snowfort_audit.domain.rule_definitions.Rule).
2. Expose a function that returns a list of your rules.
3. Register it in your pyproject.toml:

[project.entry-points."snowarch.audit.rules"]
my_rules = "my_package.rules:get_rules"

When you install your package in the same environment as snowfort-audit, your rules will automatically be included in the scan.

0. Run the examples (showcase)

Offline: A sample project with intentional violations is in examples/offline_showcase/. From the packages/snowarch-audit directory:

snowfort-audit scan --offline --path examples/offline_showcase

Use -v and --manifest for remediation details and JSON output.

Online: Seed a sandbox account with WAF violations, then run the online scan:

snowfort-audit demo-setup   # Creates bad warehouses, users, policies, etc. (uses ACCOUNTADMIN)
snowfort-audit scan         # Inspect live account and see the violations

From the monorepo root you can also run snowarch-admin demo-setup (it runs packages/snowarch-audit/examples/generate_chaos.sql).

Faster online scan: Use parallel workers (multiple Snowflake connections) to reduce run time:

snowfort audit scan --workers 4

See docs/PERFORMANCE.md for concurrency options and Native App vs client-side behavior.

1. Run Offline Scan (CI/CD)

Analyze your SQL scripts and project configuration definitions before deployment.

snowfort-audit scan --offline --path ./my-project

Example Output

The CLI renders a Rich scorecard: overall score and letter grade (A–F), per-pillar breakdown (Score, Grade, Status), and a violations table. Use -v for remediation instructions.

╭─ Snowflake Well-Architected Scorecard for ./my-project ─╮
│ Score: 94/100 (A)                                       │
╰─────────────────────────────────────────────────────────╯
        Pillar Breakdown
┌──────────────┬───────┬───────┬──────────┐
│ Pillar       │ Score │ Grade │ Status   │
├──────────────┼───────┼───────┼──────────┤
│ Security     │ 94    │ A     │ Healthy  │
│ Cost         │ 100   │ A     │ Healthy  │
└──────────────┴───────┴───────┴──────────┘

Violations (2):
 Severity   Rule       Resource    Message
 ...

2. Set connection env (once per session for online scan)

You must run login as an argument to eval so the export lines are applied to your current shell; otherwise they are only printed and scan will not see them.

eval $(snowfort login)
# or: source <(snowfort login)

Prompt for account, user, role, and authenticator; the exports set SNOWFLAKE_ACCOUNT, SNOWFLAKE_USER, etc. so the next scan uses them. Auth options in the menu: mfa (password+MFA), keypair (JWT), pat (token). If the variables are already set, login reuses them and prints the same exports.

3. Run Online Scan (Periodic)

Audit your live environment using the WAF Scorecard.

snowfort-audit scan

4. AI-Augmented Scan (Cortex)

Use Snowflake Cortex (LLM) to synthesize findings into an Executive Summary.

snowfort-audit scan --cortex

5. Planning Tools (Calculator)

Generate usage inputs for the Snowflake Pricing Calculator.

snowfort-audit calculator-inputs > pricing_inputs.json

6. JSON Manifest (Integration)

Output machine-readable violations (including pillar and remediation_instruction) for CI or downstream tools (e.g. Cortex Code Skill).

snowfort-audit scan --offline --path . --manifest

Each violation in the JSON includes rule_id, resource_name, message, severity, pillar, and remediation_instruction (actionable text for an LLM or human to generate fixes).

---

Remediation Instructions

Violations carry an optional remediation_instruction: human/LLM-readable text describing what to do. The audit is the diagnostician; fixes are intended to be managed as IaC via admin/scaffold tooling or by consuming --manifest output with Cortex Code or another LLM. See Deferred work for Cortex Code Skill and fix strategy.

---

Roadmap

• Cortex Code Skill: Invoke audit and generate remediation from remediation_instruction (see Deferred work).
• v1.0: Native App packaging, Streamlit dashboard polish, schema security for AUDIT_RESULTS. Monorepo and PyPI deployment: see MONOREPO_AND_PYPI.md.

---

Integrating with Deployments

snowarch-deploy automatically runs snowfort-audit in Offline Mode during the plan stage of your deployment pipeline, blocking deployments that violate critical WAF rules.