flecto 4.2.0 → 4.4.0

package/CHANGELOG.md

@@ -7,6 +7,49 @@ The format is based on [Keep a Changelog], and this project adheres to
 
 ## [Unreleased]
 
+## [4.4.0] - 2026-10-05
+
+### Changed
+
+- **Flag lists diff by flag name, so removing one arg is one removal**
+  ([#238]). A real pull request that removed the first of eight container
+  `args` read as 7 `changed` and 1 `removed`, each pairing two unrelated flags.
+  It now reads as `removed args["--keytoolPath"]`. A list counts when every item
+  is `-x`, `--name` or `--name=value` with unique names; a repeated `--set`,
+  `["--port", "8080"]`, and `["-c", "echo hi"]` keep the position diff, and
+  `--no-array-id` turns it off. Paths change from `args[0]` to
+  `args["--name"]` for these lists. No built-in pack rule matches an `args`
+  index.
+
+[#238]: https://github.com/myselfsiddharth/Flecto/issues/238
+
+## [4.3.0] - 2026-10-05
+
+### Fixed
+
+- **A secret-sounding key no longer hides, or raises an error over, a value
+  that cannot be a secret** ([#224]). Masking and `secret-key-changed` decided
+  on the key name alone, so on real Helm charts `secretCreatePolicy: { enabled:
+  true }` printed as `***` (hiding the one line the PR was about), and
+  `adminPasswordKey: keycloak-admin-password` (the *name* of a key inside a
+  Kubernetes Secret) failed as an error. Four of six repositories checked
+  during outreach hit it.
+
+  Under such a key a value is now judged leaf by leaf, and is not treated as a
+  secret when it is a boolean, `null`, an empty string, a reference-only
+  placeholder (`${NAME}`, `${NAME:-}`, `$(NAME)`, `{{ ... }}`, or `KEY=` one of
+  those), or a plain identifier under a key that names a Secret
+  (`existingSecret*`, `*SecretName`, `*SecretRef`, `*PasswordKey`,
+  `secretKeyRef.name`/`.key`). Numbers, `${NAME:-literal}`, and anything the
+  value detector flags are still masked and still fire. Display masking, the
+  committed snapshot store, and the rule share one predicate, so they cannot
+  disagree. It is exposed to packs as `afterSecretCandidate`.
+
+  A shared snapshot store that recorded one of these values as a digest will
+  report it as changed once, when it is first written in plain text.
+
+[#224]: https://github.com/myselfsiddharth/Flecto/issues/224
+
 ## [4.2.0] - 2026-10-05
 
 The first npm release since 4.1.1. The `v4.1.2` tag moved the documented Action
@@ -1411,7 +1454,9 @@ fixed — those runs were never actually gated — but the failure is new.
 - Misconfigured policy packs/plugins cause `watch` to exit non-zero instead of
   continuing with no policies.
 
-[Unreleased]: https://github.com/myselfsiddharth/Flecto/compare/v4.2.0...HEAD
+[Unreleased]: https://github.com/myselfsiddharth/Flecto/compare/v4.4.0...HEAD
+[4.4.0]: https://github.com/myselfsiddharth/Flecto/compare/v4.3.0...v4.4.0
+[4.3.0]: https://github.com/myselfsiddharth/Flecto/compare/v4.2.0...v4.3.0
 [4.2.0]: https://github.com/myselfsiddharth/Flecto/compare/v4.1.1...v4.2.0
 [4.1.1]: https://github.com/myselfsiddharth/Flecto/compare/v4.1.0...v4.1.1
 [4.1.0]: https://github.com/myselfsiddharth/Flecto/compare/v4.0.0...v4.1.0

package/README.md

@@ -77,7 +77,7 @@ aws_db_instance.main.#action
 
 Flecto PR Risk is on the
 [GitHub Marketplace](https://github.com/marketplace/actions/flecto-pr-risk), so
-`myselfsiddharth/Flecto@v4.1.2` is the whole reference.
+`myselfsiddharth/Flecto@v4.3.0` is the whole reference.
 
 **Terraform** — point it at the plan JSON:
 
@@ -91,7 +91,7 @@ steps:
   - run: |
       terraform plan -out=tf.plan
       terraform show -json tf.plan > plan.json
-  - uses: myselfsiddharth/Flecto@v4.1.2
+  - uses: myselfsiddharth/Flecto@v4.3.0
     with:
       terraform-plan: plan.json
       fail-on: error
@@ -109,7 +109,7 @@ steps:
     with:
       fetch-depth: 0
   - run: helm template ./chart > rendered.yaml
-  - uses: myselfsiddharth/Flecto@v4.1.2
+  - uses: myselfsiddharth/Flecto@v4.3.0
     with:
       targets: rendered.yaml
       policies: kubernetes

package/package.json

@@ -4,7 +4,7 @@
     "access": "public",
     "provenance": true
   },
-  "version": "4.2.0",
+  "version": "4.4.0",
   "description": "Reads your Terraform plan and Kubernetes changes and posts a plain-English risk summary on every pull request, blocking the dangerous ones",
   "license": "MIT",
   "keywords": [

package/schemas/flecto-policy-pack-2.0.json

@@ -44,6 +44,7 @@
         "afterTruthy": { "const": true },
         "beforeLooksSecret": { "const": true },
         "afterLooksSecret": { "const": true },
+        "afterSecretCandidate": { "const": true },
         "afterMatches": { "type": "string" },
         "afterAnyMatches": { "type": "string" },
         "numericJump": {
@@ -95,6 +96,7 @@
         "afterTruthy": { "const": true },
         "beforeLooksSecret": { "const": true },
         "afterLooksSecret": { "const": true },
+        "afterSecretCandidate": { "const": true },
         "afterMatches": { "type": "string" },
         "afterAnyMatches": { "type": "string" },
         "numericJump": { "$ref": "#/$defs/numericJump" },

package/src/differ.js

@@ -364,24 +364,43 @@ function identityMap(items, idKey) {
 // `KEY=VALUE`, or a bare `KEY` (Compose's pass-through from the host).
 export const ASSIGNMENT_RE = /^([A-Za-z_][A-Za-z0-9_.-]*)(?:=|$)/;
 
+// `-x`, `--name`, or `--name=value`: a command-line flag, keyed by its name.
+export const FLAG_RE = /^(-{1,2}[A-Za-z0-9][A-Za-z0-9_.-]*)(?:=|$)/;
+
 /**
- * Key a list of `KEY=VALUE` strings by KEY, or return null when it is not one.
+ * String-list shapes that are really maps, and how each is keyed.
  *
  * Compose writes `environment`, `labels` and `build.args` either as a map or as
- * a list of assignments, and means the same thing by both. Diffed by position,
+ * a list of `KEY=VALUE`, and means the same thing by both. Diffed by position,
  * one inserted variable turned every later line into a `changed` pairing two
- * unrelated variables (#226). At least one item must carry an `=`, so a plain
- * word list such as `command: [python, app.py]` keeps its order-sensitive diff.
+ * unrelated variables (#226); one removed container arg did the same to every
+ * later flag (#238). A list counts only when every item has the shape and keys
+ * are unique, so a repeated `--set` falls back to position.
+ *
+ * Assignments also need at least one `=`, so a plain word list such as
+ * `command: [python, app.py]` keeps its order-sensitive diff. A flag list does
+ * not: `[-v, --debug]` is already unambiguous, and `["--port", "8080"]` or
+ * `["-c", "echo hi"]` fail the shape and keep position.
+ * @type {Array<{ re: RegExp, needsValue: boolean }>}
+ */
+const KEYED_STRING_SHAPES = [
+  { re: ASSIGNMENT_RE, needsValue: true },
+  { re: FLAG_RE, needsValue: false },
+];
+
+/**
+ * Key a list of strings by the given shape, or return null when it is not one.
  * @param {unknown[]} items
+ * @param {RegExp} re
  * @returns {Map<string, { value: unknown, index: number }> | null}
  */
-function assignmentMap(items) {
+function keyedStringMap(items, re) {
   /** @type {Map<string, { value: unknown, index: number }>} */
   const map = new Map();
   for (let i = 0; i < items.length; i++) {
     const item = items[i];
     if (typeof item !== 'string') return null;
-    const match = ASSIGNMENT_RE.exec(item);
+    const match = re.exec(item);
     if (!match || map.has(match[1])) return null;
     map.set(match[1], { value: item, index: i });
   }
@@ -389,18 +408,22 @@ function assignmentMap(items) {
 }
 
 /**
- * Both sides are assignment lists and at least one item assigns a value.
+ * Both sides have the same keyed shape (see KEYED_STRING_SHAPES).
  * @param {unknown[]} before
  * @param {unknown[]} after
  * @returns {{ beforeMap: Map<string, { value: unknown, index: number }>, afterMap: Map<string, { value: unknown, index: number }> } | null}
  */
 function assignmentMaps(before, after) {
-  const beforeMap = assignmentMap(before);
-  const afterMap = beforeMap && assignmentMap(after);
-  if (!beforeMap || !afterMap) return null;
   const assigns = (item) => typeof item === 'string' && item.includes('=');
-  if (!before.some(assigns) && !after.some(assigns)) return null;
-  return { beforeMap, afterMap };
+  for (const { re, needsValue } of KEYED_STRING_SHAPES) {
+    const beforeMap = keyedStringMap(before, re);
+    const afterMap = beforeMap && keyedStringMap(after, re);
+    if (!beforeMap || !afterMap) continue;
+    if (beforeMap.size === 0 && afterMap.size === 0) continue;
+    if (needsValue && !before.some(assigns) && !after.some(assigns)) continue;
+    return { beforeMap, afterMap };
+  }
+  return null;
 }
 
 /**

package/src/packs/default.json

@@ -9,6 +9,7 @@
         "path": "(secret|token|password|api[_-]?key|private[_-]?key)",
         "pathFlags": "i"
       },
+      "afterSecretCandidate": true,
       "message": "Sensitive-looking key added or changed. Confirm secret storage, rotation, and access controls."
     },
     {

package/src/packs/strict-prod.json

@@ -9,6 +9,7 @@
         "path": "(secret|token|password|api[_-]?key|private[_-]?key|credential)",
         "pathFlags": "i"
       },
+      "afterSecretCandidate": true,
       "message": "Sensitive-looking key changed in production profile. Confirm rotation and access controls."
     },
     {

package/src/policy.js

@@ -4,7 +4,8 @@ import { createRequire } from 'module';
 import { fileURLToPath, pathToFileURL } from 'url';
 import yaml from 'js-yaml';
 import { checkPattern, compilePattern, explainPatternFailure } from './regex-engine.js';
-import { containsSecret } from './secrets.js';
+import { containsSecret, holdsSecretCandidate } from './secrets.js';
+import { secretMatchPath } from './differ.js';
 
 /**
  * @typedef {'info' | 'warn' | 'error'} PolicySeverity
@@ -29,6 +30,7 @@ import { containsSecret } from './secrets.js';
  *   afterTruthy?: true,
  *   beforeLooksSecret?: true,
  *   afterLooksSecret?: true,
+ *   afterSecretCandidate?: true,
  *   afterMatches?: string,
  *   afterAnyMatches?: string,
  *   numericJump?: { minMultiple: number },
@@ -49,6 +51,7 @@ import { containsSecret } from './secrets.js';
  *   afterTruthy?: true,
  *   beforeLooksSecret?: true,
  *   afterLooksSecret?: true,
+ *   afterSecretCandidate?: true,
  *   afterMatches?: string,
  *   afterAnyMatches?: string,
  *   numericJump?: { minMultiple: number },
@@ -102,12 +105,12 @@ const CHANGE_TYPES = new Set(['added', 'removed', 'changed']);
 const RULE_FIELDS = new Set([
   'id', 'severity', 'when', 'match', 'beforeEquals', 'afterEquals',
   'beforeIn', 'afterIn', 'beforeTruthy', 'afterTruthy', 'numericJump',
-  'beforeLooksSecret', 'afterLooksSecret',
+  'beforeLooksSecret', 'afterLooksSecret', 'afterSecretCandidate',
   'afterMatches', 'afterAnyMatches', 'numericDelta', 'allOf', 'anyOf', 'message', 'messageTemplate',
 ]);
 const CLAUSE_FIELDS = new Set([
   'match', 'beforeEquals', 'afterEquals', 'beforeIn', 'afterIn',
-  'beforeTruthy', 'afterTruthy', 'beforeLooksSecret', 'afterLooksSecret',
+  'beforeTruthy', 'afterTruthy', 'beforeLooksSecret', 'afterLooksSecret', 'afterSecretCandidate',
   'afterMatches', 'afterAnyMatches', 'numericJump', 'numericDelta',
 ]);
 const MATCH_FIELDS = new Set(['path', 'pathFlags', 'pathEquals', 'pathPrefix']);
@@ -277,6 +280,7 @@ function validateRule(candidate, location, isClause = false, trusted = false) {
   validateTruthyPredicate(rule.afterTruthy, 'afterTruthy', location);
   validateTruthyPredicate(rule.beforeLooksSecret, 'beforeLooksSecret', location);
   validateTruthyPredicate(rule.afterLooksSecret, 'afterLooksSecret', location);
+  validateTruthyPredicate(rule.afterSecretCandidate, 'afterSecretCandidate', location);
   validateRegexPredicate(rule.afterMatches, 'afterMatches', location, trusted);
   validateRegexPredicate(rule.afterAnyMatches, 'afterAnyMatches', location, trusted);
   validateNumericPredicate(rule.numericJump, 'numericJump', 'minMultiple', location, true);
@@ -878,6 +882,9 @@ function matchClause(clause, change) {
   // the redaction it triggers never disagree.
   if (clause.beforeLooksSecret && !containsSecret(change.before)) return false;
   if (clause.afterLooksSecret && !containsSecret(change.after)) return false;
+  // A secret-sounding key whose new value cannot be the secret: a boolean, an
+  // empty string, a placeholder, or a Secret reference (#224).
+  if (clause.afterSecretCandidate && !holdsSecretCandidate(change.after, secretMatchPath(change))) return false;
   if (clause.afterMatches && (typeof change.after !== 'string' || !afterMatchesRegexFor(clause).test(change.after))) return false;
   // The list counterpart, for the change that turns a scalar into a list in
   // one edit -- reported as a single `changed` event whose `after` is an array,

package/src/positions.js

@@ -3,7 +3,7 @@ import yaml from 'js-yaml';
 
 import { isArmoredAgeFile } from './encrypted.js';
 import { isEnvFilename, isIniFilename, stripJsonComments, yamlDocumentKeys } from './parser.js';
-import { ASSIGNMENT_RE } from './differ.js';
+import { ASSIGNMENT_RE, FLAG_RE } from './differ.js';
 
 /**
  * Where a config path lives in the source text (#142).
@@ -248,10 +248,13 @@ function itemByIdentity(items, quoted, arrayIdKey) {
       if (String(id) === target) matches.add(item);
     }
   }
-  // A `KEY=VALUE` list (Compose `environment`, `labels`) is keyed by KEY.
+  // A `KEY=VALUE` list (Compose `environment`, `labels`) is keyed by KEY, and
+  // a flag list (container `args`) by flag name.
   if (matches.size === 0 && !arrayIdKey) {
     for (const item of items) {
-      if (typeof item.value === 'string' && ASSIGNMENT_RE.exec(item.value)?.[1] === target) matches.add(item);
+      if (typeof item.value !== 'string') continue;
+      const key = ASSIGNMENT_RE.exec(item.value)?.[1] ?? FLAG_RE.exec(item.value)?.[1];
+      if (key === target) matches.add(item);
     }
   }
   return matches.size === 1 ? [...matches][0] : null;

package/src/renderer.js

@@ -1,5 +1,5 @@
 import chalk from 'chalk';
-import { looksLikeSecretPath, redactSecretString } from './secrets.js';
+import { isSecretCandidate, looksLikeSecretPath, redactSecretString } from './secrets.js';
 import { ENCRYPTED_DISPLAY, displayEncrypted, isEncryptedSentinel } from './encrypted.js';
 import { secretMatchPath } from './differ.js';
 
@@ -16,13 +16,12 @@ function fmt(v, opts = {}) {
   if (isEncryptedSentinel(v)) return chalk.dim(ENCRYPTED_DISPLAY);
   let value = displayEncrypted(v);
   if (opts.maskSecrets) {
-    if (opts.path && looksLikeSecretPath(opts.path)) {
-      return chalk.dim('"***"');
-    }
     // The changed path itself can look benign while the value carries secrets,
-    // e.g. "database" holding { password }. Redact those the same way the
-    // webhook/CI payloads do.
+    // e.g. "database" holding { password }; or look secret while holding none,
+    // e.g. `secretCreatePolicy: { enabled: true }`. Both are judged leaf by leaf,
+    // the same way the webhook/CI payloads are.
     value = maskSensitiveValue(value, opts.path ?? '');
+    if (value === '***') return chalk.dim('"***"');
   }
   if (typeof value === 'string') return JSON.stringify(value);
   if (typeof value === 'object' && value !== null) return JSON.stringify(value);
@@ -190,7 +189,18 @@ export function renderPolicyFindings(findings) {
  * @returns {unknown}
  */
 export function maskSensitiveValue(value, path = '') {
-  if (looksLikeSecretPath(path)) return '***';
+  // A secret-sounding key masks its scalars, not its whole subtree: under
+  // `secretCreatePolicy`, `enabled: true` is the line a reviewer needs (#224).
+  // Each leaf is judged at its own path, which still carries the key.
+  // Plain containers only: YAML reads `password: 2024-01-01` as a Date, and a
+  // Date falls through to the scalar branch below, where it is masked.
+  const isContainer = Array.isArray(value)
+    || (value !== null && typeof value === 'object'
+      && (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null));
+  if (looksLikeSecretPath(path) && !isContainer) {
+    if (isSecretCandidate(value, path)) return '***';
+    return typeof value === 'string' ? redactSecretString(value) : value;
+  }
   if (Array.isArray(value)) {
     return value.map((v, i) => maskSensitiveValue(v, `${path}[${i}]`));
   }

package/src/secrets.js

@@ -362,6 +362,100 @@ export function looksLikeSecretPath(path) {
   return SECRET_PATH_RE.test(path);
 }
 
+/**
+ * Keys that hold the *name* of a secret, not the secret: `existingSecret`,
+ * `existingSecretPasswordKey`, `tlsSecretName`, `envSecretRef`,
+ * `adminPasswordKey`. The Helm convention for "the credential lives in a
+ * Kubernetes Secret, and this is where". Deliberately not `*SecretKey`:
+ * `minio.secretKey` is the credential itself.
+ */
+const REFERENCE_KEY_RE = /^(?:existingSecret\w*|\w*Secret(?:Name|Ref)|\w*PasswordKey)$/i;
+const SECRET_KEY_REF_RE = /secretKeyRef\.(?:name|key)$/i;
+// A Kubernetes object name or a Secret key, which is what a reference holds.
+const REFERENCE_VALUE_RE = /^[A-Za-z0-9](?:[A-Za-z0-9._-]{0,251}[A-Za-z0-9])?$/;
+// `KEY=VALUE`, as Compose writes an environment list entry.
+const ASSIGNMENT_RE = /^[A-Za-z_][A-Za-z0-9_.-]*=(.+)$/s;
+/**
+ * Placeholders that can only be references, for values under a key that names
+ * a credential. Stricter than PLACEHOLDER_RE, which serves value-shape
+ * detection: there, `$uperSecret1` reading as `$NAME` costs a missed entropy
+ * hit; here it would print a password. So `${NAME}`, `${NAME:-}` and
+ * `${NAME:?message}` but not `${NAME:-literal}` (the literal is a default
+ * credential), `$(NAME)`, `{{ ... }}` with no quoted literal inside, and an
+ * already-masked `***`.
+ */
+const KEY_PLACEHOLDER_RE = /^(?:\$\{[A-Za-z_][A-Za-z0-9_]*(?::?\?[^}]*|:-)?\}|\$\([A-Za-z_][A-Za-z0-9_]*\)|\{\{[^}"'`]*\}\}|\*{3})$/;
+
+/**
+ * The last key of a diff path: `a.b.c` -> `c`, `env["X_TOKEN"]` -> `X_TOKEN`.
+ * @param {string} path
+ * @returns {string}
+ */
+function lastPathSegment(path) {
+  const quoted = /\[("(?:[^"\\]|\\.)*")\]$/.exec(path);
+  if (quoted) {
+    try {
+      return JSON.parse(quoted[1]);
+    } catch {
+      return quoted[1];
+    }
+  }
+  return path.slice(path.lastIndexOf('.') + 1);
+}
+
+/**
+ * Could this scalar, sitting under a secret-sounding key, be the secret?
+ *
+ * Key-name masking used to answer yes for anything, which hid the values a
+ * reviewer most needed (#224): `secretCreatePolicy: { enabled: true }` printed
+ * as `***`, and `adminPasswordKey: keycloak-admin-password` — the name of a key
+ * inside a Secret — raised an error. No, then, for:
+ *
+ * - booleans, null, and an empty string: nothing to hide
+ * - a placeholder (`${X}`, `$(X)`, `{{ ... }}`), alone or as `KEY=<placeholder>`
+ * - a reference: a key that names a Secret, holding a plain identifier that the
+ *   value detector does not flag
+ *
+ * Numbers stay yes (`pin: 12345` is the pin). So does `KEY=` with an empty
+ * right side: base64 padding (`c2VjcmV0=`) has exactly that shape.
+ *
+ * Shared by display masking, the committed snapshot store, and the
+ * `secret-key-changed` rule, so the three cannot disagree.
+ * @param {unknown} value
+ * @param {string} [path] the configuration path, document prefix stripped
+ * @returns {boolean}
+ */
+export function isSecretCandidate(value, path = '') {
+  if (value === null || value === undefined || typeof value === 'boolean') return false;
+  if (typeof value !== 'string') return true;
+  const trimmed = value.trim();
+  if (!trimmed || KEY_PLACEHOLDER_RE.test(trimmed)) return false;
+  const assignment = ASSIGNMENT_RE.exec(trimmed);
+  if (assignment && KEY_PLACEHOLDER_RE.test(assignment[1].trim())) return false;
+  const isReference = REFERENCE_KEY_RE.test(lastPathSegment(path)) || SECRET_KEY_REF_RE.test(path);
+  if (isReference && REFERENCE_VALUE_RE.test(trimmed) && !looksLikeSecret(trimmed)) return false;
+  return true;
+}
+
+/**
+ * True when any scalar inside `value` could be a secret (see
+ * `isSecretCandidate`), each judged at its own path.
+ * @param {unknown} value
+ * @param {string} [path]
+ * @returns {boolean}
+ */
+export function holdsSecretCandidate(value, path = '') {
+  if (Array.isArray(value)) return value.some((entry, index) => holdsSecretCandidate(entry, `${path}[${index}]`));
+  if (
+    value
+    && typeof value === 'object'
+    && (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null)
+  ) {
+    return Object.entries(value).some(([key, entry]) => holdsSecretCandidate(entry, path ? `${path}.${key}` : key));
+  }
+  return isSecretCandidate(value, path);
+}
+
 /**
  * True when a value — or any string nested inside a plain object or array —
  * looks like a secret.

package/src/snapshot-store.js

@@ -11,7 +11,7 @@ import { createHash } from 'crypto';
 import { execFileSync } from 'child_process';
 import { dirname, isAbsolute, join, relative, resolve, sep } from 'path';
 
-import { containsSecret, looksLikeSecretPath } from './secrets.js';
+import { containsSecret, isSecretCandidate, looksLikeSecretPath } from './secrets.js';
 import { documentKeysOf, withDocumentKeys } from './documents.js';
 
 /**
@@ -666,7 +666,11 @@ export function maskState(state, path = '') {
   if (isMaskedDigest(state)) return state;
   // `String(state)` because a credential is not always a string — `password:
   // 12345` parses as a number, and it is still the password.
-  if (looksLikeSecretPath(path)) return maskedDigest(String(state));
+  // The same leaf rule as the renderer (#224): a boolean, an empty string, a
+  // placeholder, or a Secret reference under a secret-sounding key is not the
+  // secret. The store must never be more permissive than the display, and this
+  // is the one predicate both use.
+  if (looksLikeSecretPath(path) && isSecretCandidate(state, path)) return maskedDigest(String(state));
   if (typeof state === 'string') return containsSecret(state) ? maskedDigest(state) : state;
   return state;
 }