flecto 2.0.0 → 3.0.0

package/src/packs/sops.json

@@ -0,0 +1,61 @@
+{
+  "id": "sops",
+  "rules": [
+    {
+      "id": "sops-file-decrypted",
+      "severity": "error",
+      "when": ["changed"],
+      "match": { "pathEquals": "<encryption>" },
+      "afterEquals": "plaintext",
+      "message": "This file was encrypted and is now plaintext. Treat every value in it as exposed: rotate the secrets, then restore encryption before merging."
+    },
+    {
+      "id": "sops-value-decrypted",
+      "severity": "error",
+      "when": ["changed"],
+      "afterEquals": "<no longer encrypted>",
+      "messageTemplate": "{path} was an encrypted value and is now stored in the clear. Rotate it and re-encrypt the file."
+    },
+    {
+      "id": "sops-recipient-added",
+      "severity": "error",
+      "when": ["added"],
+      "match": {
+        "path": "(?:^|\\.)sops\\.(kms|gcp_kms|azure_kv|hc_vault|age|pgp)(?:$|[.\\[])"
+      },
+      "messageTemplate": "A decryption recipient was added at {path}. That key can now decrypt this file — confirm it is authorized and that the change was intended."
+    },
+    {
+      "id": "sops-recipient-removed",
+      "severity": "warn",
+      "when": ["removed"],
+      "match": {
+        "path": "(?:^|\\.)sops\\.(kms|gcp_kms|azure_kv|hc_vault|age|pgp)(?:$|[.\\[])"
+      },
+      "messageTemplate": "A decryption recipient was removed at {path}. Anything that key already read stays readable to its holder — rotate the secrets if the removal was a revocation."
+    },
+    {
+      "id": "sops-mac-changed-without-value-change",
+      "severity": "warn",
+      "when": ["changed"],
+      "match": { "pathEquals": "<encryption.mac>" },
+      "message": "The SOPS MAC changed but no value it covers did. A normal edit moves both together, so this points at a hand-edited or tampered metadata block."
+    },
+    {
+      "id": "sops-file-encrypted",
+      "severity": "info",
+      "when": ["changed"],
+      "match": { "pathEquals": "<encryption>" },
+      "beforeEquals": "plaintext",
+      "message": "This file is now encrypted. Confirm the values it held while plaintext were rotated — git history still has them."
+    },
+    {
+      "id": "sops-creation-rule-recipients-changed",
+      "severity": "warn",
+      "match": {
+        "path": "^creation_rules\\b.*\\b(kms|gcp_kms|azure_kv|hc_vault|age|pgp|key_groups)\\b"
+      },
+      "messageTemplate": "A SOPS creation rule changed at {path}. This decides who future encryptions are readable by; existing files keep their current recipients until they are re-encrypted."
+    }
+  ]
+}

package/src/packs/strict-prod.json

@@ -11,6 +11,16 @@
       },
       "message": "Sensitive-looking key changed in production profile. Confirm rotation and access controls."
     },
+    {
+      "id": "secret-value-detected",
+      "severity": "error",
+      "when": ["added", "changed", "removed"],
+      "anyOf": [
+        { "afterLooksSecret": true },
+        { "beforeLooksSecret": true }
+      ],
+      "message": "Value looks like a credential (known token format or high-entropy string) regardless of its key name. Treat it as exposed: move it to a secret store and rotate it."
+    },
     {
       "id": "dangerous-toggle-enabled",
       "severity": "error",
@@ -19,7 +29,7 @@
         "path": "(debug|allow_insecure|disable_tls|skip_tls_verify|permit_all)",
         "pathFlags": "i"
       },
-      "afterEquals": true,
+      "afterTruthy": true,
       "message": "Dangerous toggle enabled in production profile."
     },
     {

package/src/packs/terraform.json

@@ -0,0 +1,120 @@
+{
+  "id": "terraform",
+  "rules": [
+    {
+      "id": "terraform-resource-replaced",
+      "severity": "error",
+      "when": ["removed"],
+      "match": {
+        "path": "\\.#action$"
+      },
+      "beforeEquals": "replace",
+      "message": "Terraform will destroy and recreate this resource. Expect downtime, a new resource id, and the loss of anything held only on the existing instance. Check which attribute forced the replacement."
+    },
+    {
+      "id": "terraform-stateful-resource-destroyed",
+      "severity": "error",
+      "when": ["removed"],
+      "match": {
+        "path": "(^|\\.)(aws_db_instance|aws_db_cluster_snapshot|aws_rds_cluster|aws_rds_cluster_instance|aws_dynamodb_table|aws_s3_bucket|aws_ebs_volume|aws_efs_file_system|aws_elasticache_cluster|aws_elasticache_replication_group|aws_redshift_cluster|aws_docdb_cluster|aws_neptune_cluster|google_sql_database_instance|google_storage_bucket|azurerm_storage_account|azurerm_mssql_database)\\..*\\.#action$"
+      },
+      "beforeIn": ["delete", "replace"],
+      "message": "Terraform will destroy a stateful resource. Its data does not survive. Take a final snapshot, or add a prevent_destroy lifecycle block, before applying."
+    },
+    {
+      "id": "terraform-security-group-open-ingress",
+      "severity": "error",
+      "when": ["added", "changed"],
+      "afterIn": ["0.0.0.0/0", "::/0"],
+      "anyOf": [
+        {
+          "match": {
+            "path": "(^|\\.)aws_security_group\\..*\\.ingress\\[[^\\]]*\\]\\.(ipv6_)?cidr_blocks\\[[^\\]]*\\]$"
+          }
+        },
+        {
+          "match": {
+            "path": "(^|\\.)aws_vpc_security_group_ingress_rule\\..*\\.cidr_ipv[46]$"
+          }
+        }
+      ],
+      "messageTemplate": "Security group ingress will accept traffic from the whole internet ({after}). Restrict the source to a known CIDR, a prefix list, or another security group."
+    },
+    {
+      "id": "terraform-iam-wildcard",
+      "severity": "error",
+      "when": ["added", "changed"],
+      "match": {
+        "path": "(^|\\.)aws_iam_[a-z_]+\\..*\\.policy$"
+      },
+      "afterMatches": "\"(Action|NotAction|Resource|NotResource)\"\\s*:\\s*(\"\\*\"|\\[[^\\]]*\"\\*\")",
+      "message": "IAM policy grants a wildcard action or resource (\"*\"). Scope it to the specific actions and ARNs the principal needs."
+    },
+    {
+      "id": "terraform-s3-public-access-block-disabled",
+      "severity": "error",
+      "when": ["added", "changed", "removed"],
+      "anyOf": [
+        {
+          "match": {
+            "path": "(^|\\.)aws_s3_bucket_public_access_block\\..*\\.(block_public_acls|block_public_policy|ignore_public_acls|restrict_public_buckets)$"
+          },
+          "afterEquals": false
+        },
+        {
+          "match": {
+            "path": "(^|\\.)aws_s3_bucket_public_access_block\\..*\\.#action$"
+          },
+          "beforeIn": ["delete", "replace"]
+        }
+      ],
+      "message": "S3 public access block is being turned off or removed. Leave all four block_public_* settings enabled unless the bucket is deliberately a public website."
+    },
+    {
+      "id": "terraform-s3-public-acl",
+      "severity": "error",
+      "when": ["added", "changed"],
+      "match": {
+        "path": "(^|\\.)aws_s3_bucket(_acl)?\\..*\\.acl$"
+      },
+      "afterIn": ["public-read", "public-read-write", "authenticated-read"],
+      "messageTemplate": "S3 bucket ACL set to \"{after}\", which exposes objects outside the account. Use a bucket policy scoped to known principals instead."
+    },
+    {
+      "id": "terraform-instance-size-changed",
+      "severity": "warn",
+      "when": ["changed"],
+      "match": {
+        "path": "(^|\\.)(aws_instance|aws_db_instance|aws_rds_cluster_instance|aws_launch_template|aws_launch_configuration|aws_elasticache_cluster|google_compute_instance|azurerm_linux_virtual_machine|azurerm_windows_virtual_machine)\\..*\\.(instance_type|instance_class|node_type|machine_type|size|vm_size)$"
+      },
+      "messageTemplate": "Instance size changes from {before} to {after}. Confirm the cost impact, and whether the change forces a restart or a replacement."
+    },
+    {
+      "id": "terraform-capacity-jump",
+      "severity": "warn",
+      "when": ["changed"],
+      "match": {
+        "path": "\\.(desired_capacity|max_size|min_size|desired_count|node_count|initial_node_count|instance_count|number_of_nodes|max_capacity|min_capacity)$"
+      },
+      "numericJump": { "minMultiple": 2 },
+      "messageTemplate": "Capacity at {path} jumps from {before} to {after} (>=2x). Confirm the quota headroom and the cost of the new floor."
+    },
+    {
+      "id": "terraform-sensitive-value-changed",
+      "severity": "warn",
+      "when": ["added", "changed", "removed"],
+      "anyOf": [
+        { "afterEquals": "(sensitive value)" },
+        { "beforeEquals": "(sensitive value)" }
+      ],
+      "message": "A value Terraform marks sensitive is being set, changed, or removed. Flecto redacted it. Confirm it lives in a secret store and that anything depending on it is rotated."
+    },
+    {
+      "id": "terraform-hardcoded-credential",
+      "severity": "error",
+      "when": ["added", "changed"],
+      "afterLooksSecret": true,
+      "message": "A planned attribute value looks like a credential (known token format or high-entropy string) that Terraform did not mark sensitive. Move it to a secret store and rotate it."
+    }
+  ]
+}

package/src/parser.js

@@ -3,8 +3,10 @@ import { basename, extname } from 'path';
 import yaml from 'js-yaml';
 import TOML from '@iarna/toml';
 import dotenv from 'dotenv';
+import { isArmoredAgeFile, normalizeEncrypted, opaqueFileState } from './encrypted.js';
+import { documentKeysOf, withDocumentKeys } from './documents.js';
 
-const SUPPORTED_EXT = ['.json', '.yaml', '.yml', '.toml', '.env', '.ini'];
+const SUPPORTED_EXT = ['.json', '.yaml', '.yml', '.toml', '.env', '.ini', '.age'];
 
 /**
  * True for dotenv-like names: `.env`, `.env.*`, `*.env`
@@ -65,11 +67,175 @@ export function parseIni(raw) {
 }
 
 function isPlainObject(v) {
-  return v !== null && typeof v === 'object' && !Array.isArray(v);
+  if (v === null || typeof v !== 'object' || Array.isArray(v)) return false;
+  const prototype = Object.getPrototypeOf(v);
+  return prototype === Object.prototype || prototype === null;
+}
+
+/**
+ * What a YAML anchor that points back at one of its own containers collapses
+ * to. See {@link normalizeParsedValue} for why this is necessary and why a
+ * plain sentinel, rather than e.g. a path reference, is enough.
+ */
+export const CIRCULAR_SENTINEL = '<circular>';
+
+/**
+ * Convert parser-specific scalar objects into a stable JSON-safe tree before
+ * they reach snapshots, the differ, or output renderers.
+ *
+ * A recursive YAML anchor (`a: &x\n  b: *x`) parses to a genuinely cyclic
+ * object — js-yaml resolves the alias to the *same* object reference, not a
+ * copy, so `a.b === a`. `ancestors` tracks the containers on the path
+ * currently being walked, the same ancestor-tracking pattern `collectLeaves`
+ * in policy.js uses for the same reason; revisiting one replaces the
+ * back-reference with {@link CIRCULAR_SENTINEL} instead of recursing into it.
+ * A value merely reached twice by separate branches (not an ancestor of
+ * itself) is still normalized in full on each branch.
+ *
+ * The result is always plain JSON: safe for `JSON.stringify` at the snapshot
+ * write, and safe for the differ, which never sees a cycle because nothing
+ * downstream of this function ever does. The sentinel is a fixed string
+ * rather than e.g. a back-reference path, so two files with the same cycle
+ * shape normalize to the same tree and compare equal — the whole point of a
+ * stable, readable diff path.
+ * @param {unknown} value
+ * @param {Set<object>} [ancestors] internal recursion state; omit when calling
+ * @returns {unknown}
+ */
+function normalizeParsedValue(value, ancestors = new Set()) {
+  if (typeof value === 'bigint') return String(value);
+  if (typeof value === 'number' && !Number.isFinite(value)) return String(value);
+  if (value instanceof Date) return value.toJSON();
+  if (Array.isArray(value)) {
+    if (ancestors.has(value)) return CIRCULAR_SENTINEL;
+    ancestors.add(value);
+    const out = value.map((item) => normalizeParsedValue(item, ancestors));
+    ancestors.delete(value);
+    return out;
+  }
+  if (
+    value !== null
+    && typeof value === 'object'
+    && typeof value.toJSON === 'function'
+  ) {
+    const serialized = value.toJSON();
+    if (serialized !== value && (serialized === null || typeof serialized !== 'object')) {
+      return normalizeParsedValue(serialized, ancestors);
+    }
+  }
+  if (isPlainObject(value)) {
+    if (ancestors.has(value)) return CIRCULAR_SENTINEL;
+    ancestors.add(value);
+    const out = Object.fromEntries(
+      Object.entries(value).map(([key, child]) => [key, normalizeParsedValue(child, ancestors)]),
+    );
+    ancestors.delete(value);
+    return out;
+  }
+  return value;
+}
+
+/**
+ * Read a scalar field as a non-empty string, or null.
+ * @param {Record<string, unknown>} obj
+ * @param {string} key
+ * @returns {string | null}
+ */
+function scalarField(obj, key) {
+  const value = obj[key];
+  if (value == null || typeof value === 'object') return null;
+  const text = String(value).trim();
+  return text === '' ? null : text;
+}
+
+/**
+ * Stable identity for one document of a multi-document YAML file.
+ * Kubernetes-shaped documents key on `kind/name`, with the namespace inserted
+ * when present (`kind/namespace/name`). Anything else falls back to a top-level
+ * `id` then `name`, mirroring array identity matching in the differ.
+ * @param {unknown} doc
+ * @returns {string | null} null when the document has no stable identity
+ */
+function documentIdentity(doc) {
+  if (!isPlainObject(doc)) return null;
+
+  const kind = scalarField(doc, 'kind');
+  const metadata = isPlainObject(doc.metadata) ? doc.metadata : null;
+  const name = metadata ? scalarField(metadata, 'name') : null;
+  if (kind && name) {
+    const namespace = scalarField(metadata, 'namespace');
+    return namespace ? `${kind}/${namespace}/${name}` : `${kind}/${name}`;
+  }
+
+  return scalarField(doc, 'id') ?? scalarField(doc, 'name');
+}
+
+/**
+ * Keys for a multi-document file: identities when every document has a unique
+ * one, otherwise document indices. It is all-or-nothing so keys within one file
+ * stay homogeneous.
+ * @param {unknown[]} docs
+ * @returns {string[]}
+ */
+function documentKeys(docs) {
+  const identities = docs.map((doc) => {
+    const identity = documentIdentity(doc);
+    // "__proto__" as a key would mutate the prototype instead of adding an
+    // entry, silently losing the document. Fall back to indices instead.
+    return identity === '__proto__' ? null : identity;
+  });
+  const unique = new Set(identities);
+  if (!identities.includes(null) && unique.size === identities.length) {
+    return /** @type {string[]} */ (identities);
+  }
+  return docs.map((_, index) => String(index));
+}
+
+/**
+ * Parse a YAML stream, supporting `---`-separated multi-document files.
+ *
+ * A file holding a single document parses to that document unchanged, so diff
+ * paths for ordinary YAML are untouched. A file holding several documents
+ * parses to an object keyed per document, which lets the differ walk it like
+ * any other tree. Empty documents (a leading or trailing `---`, or a `null`
+ * document) are dropped, so a stray separator does not create a phantom entry.
+ *
+ * The keys it invents are recorded on the wrapper (see documents.js) so that
+ * everything downstream can tell a synthetic document prefix from a real
+ * configuration key without having to guess from its shape.
+ * @param {string} raw
+ * @returns {unknown}
+ * @throws {Error} on YAML syntax errors
+ */
+export function parseYamlStream(raw) {
+  const docs = yaml.loadAll(raw).filter((doc) => doc != null);
+
+  if (docs.length === 0) return withDocumentKeys({}, []);
+  if (docs.length === 1) return withDocumentKeys(docs[0], []);
+
+  const keys = documentKeys(docs);
+  /** @type {Record<string, unknown>} */
+  const out = {};
+  for (let i = 0; i < docs.length; i++) {
+    out[keys[i]] = docs[i];
+  }
+  return withDocumentKeys(out, keys);
 }
 
 /**
  * Auto-detect the format of a file and parse it into a plain JS object.
+ *
+ * The parsed tree then goes through the encryption pass (see encrypted.js),
+ * which replaces every ciphertext-bearing value with an opaque sentinel. Doing
+ * it here rather than at render time is what makes the guarantee absolute:
+ * nothing downstream — diff, snapshot, webhook, report — is ever handed
+ * ciphertext, because the parser never produces any. A file with nothing to
+ * redact comes back as the very same object.
+ *
+ * The multi-document keys invented by `parseYamlStream` are handed to the
+ * encryption pass explicitly — a SOPS block sits inside each document, not at
+ * the root — and re-recorded on the returned tree, since normalization may have
+ * replaced the object the mark was on.
  * @param {string} filepath
  * @param {string} raw
  * @returns {unknown}
@@ -87,26 +253,26 @@ export function parseContent(filepath, raw) {
       `Supported extensions: ${supported}`
     );
   }
-  try {
-    if (envLike || ext === '.env') {
-      return dotenv.parse(raw);
-    }
 
-    if (iniLike) {
-      return parseIni(raw);
-    }
-
-    if (ext === '.json') {
-      return JSON.parse(raw);
-    }
-
-    if (ext === '.yaml' || ext === '.yml') {
-      const result = yaml.load(raw);
-      return result == null ? {} : result;
-    }
+  // A `.age` file, and any file that opens with the age armor header, is one
+  // opaque blob rather than a config document. There is no structure to parse
+  // and no parser that would not be guessing.
+  if (ext === '.age' || isArmoredAgeFile(raw)) {
+    return opaqueFileState(raw);
+  }
 
-    if (ext === '.toml') {
-      return TOML.parse(raw);
+  let parsed;
+  try {
+    if (envLike || ext === '.env') {
+      parsed = dotenv.parse(raw);
+    } else if (iniLike) {
+      parsed = parseIni(raw);
+    } else if (ext === '.json') {
+      parsed = JSON.parse(raw);
+    } else if (ext === '.yaml' || ext === '.yml') {
+      parsed = parseYamlStream(raw);
+    } else if (ext === '.toml') {
+      parsed = TOML.parse(raw);
     }
   } catch (err) {
     const lineMatch = err.message?.match(/line (\d+)/i);
@@ -115,6 +281,9 @@ export function parseContent(filepath, raw) {
       `Parse error in "${filepath}"${lineInfo}: ${err.message}`
     );
   }
+
+  const keys = documentKeysOf(parsed) ?? [];
+  return withDocumentKeys(normalizeEncrypted(normalizeParsedValue(parsed), keys), keys);
 }
 
 /**

package/src/policy-test.js

@@ -0,0 +1,124 @@
+import { existsSync, readFileSync } from 'fs';
+import { join, resolve } from 'path';
+
+import { diffTrees } from './differ.js';
+import { parseFile } from './parser.js';
+import { evaluatePolicies } from './policy.js';
+
+const DEFAULT_CONFIG_NAME = 'flecto-policy-test.json';
+
+function readJson(path, label) {
+  if (!existsSync(path)) {
+    throw new Error(`Policy fixture ${label} not found: ${path}`);
+  }
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch (err) {
+    throw new Error(`Policy fixture ${label} is not valid JSON: ${path}: ${err.message}`);
+  }
+}
+
+function validateExpectedFinding(finding, index) {
+  if (!finding || typeof finding !== 'object') {
+    throw new Error(`Policy fixture expected[${index}] must be an object`);
+  }
+  for (const field of ['id', 'severity', 'path']) {
+    if (typeof finding[field] !== 'string' || !finding[field]) {
+      throw new Error(`Policy fixture expected[${index}].${field} must be a non-empty string`);
+    }
+  }
+}
+
+function findingKey(finding) {
+  return `${finding.id}\u0000${finding.severity}\u0000${finding.path}`;
+}
+
+function displayFinding(finding) {
+  return `${finding.severity} ${finding.id} at ${finding.path}`;
+}
+
+/**
+ * Compare findings by id, severity, and path, ignoring messages and pack labels.
+ * @param {import('./policy.js').PolicyFinding[]} actual
+ * @param {Array<{id: string, severity: string, path: string}>} expected
+ */
+export function assertExpectedFindings(actual, expected) {
+  const expectedByKey = new Map();
+  const actualByKey = new Map();
+  for (const finding of expected) {
+    const key = findingKey(finding);
+    expectedByKey.set(key, (expectedByKey.get(key) ?? 0) + 1);
+  }
+  for (const finding of actual) {
+    const key = findingKey(finding);
+    actualByKey.set(key, (actualByKey.get(key) ?? 0) + 1);
+  }
+
+  const missing = [];
+  const unexpected = [];
+  for (const finding of expected) {
+    const key = findingKey(finding);
+    if ((actualByKey.get(key) ?? 0) > 0) {
+      actualByKey.set(key, actualByKey.get(key) - 1);
+    } else {
+      missing.push(finding);
+    }
+  }
+  for (const finding of actual) {
+    const key = findingKey(finding);
+    if ((expectedByKey.get(key) ?? 0) > 0) {
+      expectedByKey.set(key, expectedByKey.get(key) - 1);
+    } else {
+      unexpected.push(finding);
+    }
+  }
+
+  if (missing.length === 0 && unexpected.length === 0) return;
+
+  const lines = ['Policy fixture findings did not match.'];
+  if (missing.length > 0) {
+    lines.push('Missing findings:');
+    lines.push(...missing.map((finding) => `  - ${displayFinding(finding)}`));
+  }
+  if (unexpected.length > 0) {
+    lines.push('Unexpected findings:');
+    lines.push(...unexpected.map((finding) => `  - ${displayFinding(finding)}`));
+  }
+  throw new Error(lines.join('\n'));
+}
+
+/**
+ * Run a policy fixture stored in a directory.
+ * @param {string} fixtureDir
+ * @param {{ configName?: string }} [options]
+ */
+export async function testPolicyFixture(fixtureDir, options = {}) {
+  const dir = resolve(fixtureDir);
+  const configName = options.configName ?? DEFAULT_CONFIG_NAME;
+  const configPath = join(dir, configName);
+  const config = readJson(configPath, 'config');
+  if (!Array.isArray(config.expected)) {
+    throw new Error(`Policy fixture config must contain an expected array: ${configPath}`);
+  }
+  config.expected.forEach(validateExpectedFinding);
+
+  const baselinePath = resolve(dir, config.baseline ?? 'baseline.json');
+  const currentPath = resolve(dir, config.current ?? 'current.json');
+  const baseline = readJson(baselinePath, 'baseline');
+  if (!existsSync(currentPath)) {
+    throw new Error(`Policy fixture current file not found: ${currentPath}`);
+  }
+
+  const changes = diffTrees(baseline.state ?? baseline, parseFile(currentPath));
+  const findings = await evaluatePolicies(changes, {
+    cwd: dir,
+    file: currentPath,
+    profile: config.profile ?? null,
+    source: config.source ?? 'ci',
+    policies: config.policies,
+    plugins: config.plugins,
+  });
+  assertExpectedFindings(findings, config.expected);
+
+  return { fixtureDir: dir, changes, findings };
+}