3squaredcircles/vatra repository overview

Visit https://docs.3squaredcircles.com⁠ for a deep dive into configuration.

Feedback welcomed at https://www.linkedin.com/company/3-squared-circles/⁠

⁠3SC Vatra

The Continuous Data Governance Auditor for Your Live Database.

3SC Vatra is an automated data security and governance tool that runs inside your CI/CD pipeline. It provides a continuous, policy-driven audit of your production database, allowing you to find sensitive data exposures and enforce governance rules in near-real-time.

Vatra connects directly to your live database and performs a deep, comprehensive scan of the actual data based on a vatra.audit.json configuration file you define. This allows it to detect sensitive data exposures (PII, PHI, credentials), policy violations, and "toxic data combinations" as soon as they appear. When run in a pipeline, it can gate deployments if violations are found, forcing an investigation before further changes are made.

⁠A Note on the Name

Vatra is a Slavic word for "fire" or "watchfire." This name was chosen because the tool acts as a "watchfire" for your database, constantly scanning and guarding your data. It shines a light into the darkest corners of your database to find hidden risks and sensitive information, helping to "purify" your data of unintended exposures.

---

⁠For the Manager (CISO, Compliance Officer, Data Governance Lead)

Vatra transforms data governance from a periodic, manual chore into an automated, continuous process.

Vatra answers your critical questions:

• "How can we be sure that no PII exists in our new analytics tables, right now?"
• "How do we move from slow, periodic audits to a state of continuous, automated compliance?"
• "How can we enforce data separation policies in our live production database?"

⁠Key Business Values:

• Achieve Continuous Compliance: Integrate data handling policies directly into your development workflow.
• Drastically Reduce Time-to-Detection: Detect data spillages on every CI run, reducing the risk window and blast radius.
• Create a Living, Auditable Exception Record: The vatra.exceptions.json file provides a historically tracked record of all approved risks.

---

⁠For the Architect & Engineer

Vatra treats data governance as code, providing a fast feedback loop to ensure production data remains compliant.

⁠The Policy-First Workflow:

1. Define Patterns: Detection rules are defined via regex in vatra.patterns.json. Vatra ships with a built-in library of common patterns (credit cards, SSNs, etc.).
2. Compose Policies: Rules are grouped into logical, named policies in vatra.policies.json (e.g., a "PII Policy" that includes the SSN and Email rules).
3. Scope the Audit: vatra.audit.json defines which tables to scan and which policies to apply to them.
4. Manage Exceptions: Approvals for known, acceptable violations are documented in vatra.exceptions.json, providing a clear, version-controlled audit trail of risk acceptance.

---

⁠For the Platform Engineer (DevOps, SRE)

Vatra is a containerized tool designed to provide a critical data security gate for automated pipelines.

⁠Execution Modes:

• execute The primary CI mode. Scans the database based on the configuration files, generates a vatra-report.json artifact, and returns a pass/fail exit code.
• interactive: Starts a local web server for building configuration files, triaging violations, and managing exceptions.
• serve-docs: Starts a lightweight server to display embedded tool documentation.

⁠Configuration & Produced Artifacts

Vatra uses a "governance as code" model, where version-controlled JSON files define the tool's behavior and store its results.

---

⁠Configuration via Environment Variables

Vatra is configured exclusively through environment variables and follows two core principles: The Override Hierarchy and the "WHERE vs. WHAT" model for secrets.

⁠Principle 1: The Override Hierarchy

1. Tool-Specific (VATRA_*): An environment variable is the most specific and will always be used if present.
2. Universal (3SC_*): If a VATRA_* variable is not found, the tool looks for a corresponding 3SC_* variable.
3. Hard-coded Default: If neither is set, the tool falls back to a safe, built-in default.

⁠Principle 2: "WHERE vs. WHAT" for Secrets Management

• The "WHERE" (The Connection): These variables tell the tool where your secrets vault is and how to authenticate (e.g., 3SC_VAULT_TYPE, VATRA_DB_VAULT_TYPE).
• The "WHAT" (The Secret Name): These variables tell the tool what specific secret to retrieve (e.g., VATRA_DB_VAULT_KEY).

Verifying Image Signatures All published images are signed with Cosign. To verify:

Install cosign: https://docs.sigstore.dev/cosign/system_config/installation/⁠ Download our public key: curl -O https://www.3squaredsquaredcircles.com/keys/3squaredcircles.pub⁠ Verify: cosign verify --key 3squaredcircles.pub 3squaredcircles/vatra:latest