flecto 3.0.0 → 3.0.1

package/CHANGELOG.md

@@ -7,6 +7,37 @@ The format is based on [Keep a Changelog], and this project adheres to
 
 ## [Unreleased]
 
+## [3.0.1] - 2026-08-07
+
+### Security
+
+- **Policy plugins declared in `.flectorc` are no longer loaded**
+  ([GHSA-wq8m-fc3q-8m5x], critical). A pull request that added a `.flectorc`
+  with a `plugins` entry achieved **arbitrary code execution on the CI runner** —
+  `flecto ci` is what teams run on pull requests, and it honoured the attacker's
+  config with no opt-in, no allowlist, and no path containment. The attacker's
+  code ran with whatever the workflow exposed, including `GITHUB_TOKEN`, and the
+  path was not contained, so `../../../../tmp/x.mjs` loaded a module from
+  anywhere on disk.
+
+  Plugins now load only from an explicit `--plugins` flag. If a config file is
+  genuinely trusted, set `FLECTO_ALLOW_RC_PLUGINS=1`; even then an rc-declared
+  plugin must live inside the working directory. Flecto **fails loudly** rather
+  than skipping the plugin silently, because a policy plugin that stopped running
+  without saying so would quietly weaken a gate the operator believes is
+  enforced.
+
+  Policy *packs* are declarative and were never affected. `--plugins` is
+  unchanged, including paths outside the project, since the flag is operator
+  intent rather than attacker input.
+
+  **If you run Flecto on untrusted pull requests, upgrade.** If you rely on
+  `plugins` in `.flectorc`, move it to `--plugins` or set the opt-in.
+
+  The trust boundary is now documented in [plugin authoring](docs/plugins.md);
+  it previously was not stated anywhere.
+
+
 ## [3.0.0] - 2026-08-06
 
 ### Migration notes
@@ -472,7 +503,8 @@ 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/v3.0.0...HEAD
+[Unreleased]: https://github.com/myselfsiddharth/Flecto/compare/v3.0.1...HEAD
+[3.0.1]: https://github.com/myselfsiddharth/Flecto/compare/v3.0.0...v3.0.1
 [3.0.0]: https://github.com/myselfsiddharth/Flecto/compare/v2.1.0...v3.0.0
 [2.1.0]: https://github.com/myselfsiddharth/Flecto/compare/v2.0.0...v2.1.0
 [#6]: https://github.com/myselfsiddharth/Flecto/issues/6
@@ -531,3 +563,4 @@ fixed — those runs were never actually gated — but the failure is new.
 [#110]: https://github.com/myselfsiddharth/Flecto/issues/110
 [Keep a Changelog]: https://keepachangelog.com/en/1.1.0/
 [Semantic Versioning]: https://semver.org/spec/v2.0.0.html
+[GHSA-wq8m-fc3q-8m5x]: https://github.com/myselfsiddharth/Flecto/security/advisories/GHSA-wq8m-fc3q-8m5x

package/README.md

@@ -35,6 +35,18 @@ English, flags what looks risky, and gives you an exit code to gate on.
 | Hope someone notices `debug: true` | Policy finding → build fails |
 | "Something in `.env` changed" | The exact keys, with secrets masked |
 
+The same engine reads whatever your change actually lives in:
+
+| You are reviewing | Flecto reads |
+|---|---|
+| App config — YAML, JSON, TOML, INI, dotenv | the files directly |
+| A Terraform change | `terraform show -json` output, via `flecto plan` |
+| A Kubernetes change | rendered manifests from `helm`, `kustomize`, or anything else |
+| A SOPS-encrypted file | its structure and recipients — **never its plaintext** |
+
+It never invokes `terraform`, `helm`, `kustomize`, `sops`, or `age`, so nothing
+extra has to exist on the CI runner.
+
 ---
 
 ## Install
@@ -285,6 +297,37 @@ resource. Flecto never runs `helm` or `kustomize` — you render, it diffs, so a
 renderer works and no binary is needed in CI.
 → **[Kubernetes](docs/kubernetes.md)**
 
+### Read a Terraform plan in plain English
+
+`terraform plan` output is precise and long. Flecto turns it into the handful of
+lines a reviewer actually needs to argue about:
+
+```bash
+terraform show -json plan.tfplan > plan.json
+flecto plan plan.json --fail-on error
+```
+
+```
+plan.json — plan format 1.2
+Plan: 0 to add, 1 to change, 0 to destroy, 1 to replace.
+  ~ aws_security_group.web.ingress[0].cidr_blocks[0]: "10.0.0.0/8" → "0.0.0.0/0"
+  - aws_db_instance.main.#action: "replace" [terraform will destroy and recreate aws_db_instance.main]
+  ~ aws_db_instance.main.password: "(sensitive value)" → "(sensitive value)" [sensitive]
+  ! policy(error) [terraform] …cidr_blocks[0]: Security group ingress will accept
+    traffic from the whole internet (0.0.0.0/0). Restrict the source to a known CIDR…
+  ! policy(error) [terraform] …#action: Terraform will destroy a stateful resource.
+    Its data does not survive. Take a final snapshot, or add a prevent_destroy…
+```
+
+A **replace reads as a removal**, not a benign update — a recreated database
+should never look like a config tweak. Values Terraform marks sensitive are
+redacted during parsing, before the policy engine or any formatter sees them, and
+`after_unknown` renders as `(known after apply)` rather than `null`.
+
+**Flecto never runs `terraform`** — you produce the JSON, it reads it, so nothing
+extra has to exist on the CI runner.
+→ **[Terraform plans](docs/terraform.md)**
+
 ### Encode your own rules
 
 Beyond the built-in packs, write rules as declarative JSON or YAML — no code:
@@ -365,6 +408,11 @@ and runs no code from the package. →
 | dotenv | `.env`, `.env.*`, `*.env` |
 | age (armored) | `.age`, or any file whose contents are one armored blob |
 
+Terraform plan JSON (`terraform show -json`) is read by **`flecto plan`**, which
+applies Terraform's own sensitivity marking. Point `plan` at it rather than `ci`
+or `watch` — those treat it as ordinary JSON and will print values Terraform
+marks sensitive ([#113](https://github.com/myselfsiddharth/Flecto/issues/113)).
+
 Multi-document YAML (`---`-separated, the usual shape of a Kubernetes manifest)
 is supported. Each document is diffed under its own key — `kind/name` for
 Kubernetes-shaped documents, so a document inserted at the top of the file does

package/index.js

@@ -484,8 +484,9 @@ program
     try {
       const { config } = loadRcConfig(process.cwd());
       const profile = resolveProfileName(opts.profile);
-      const effective = resolveEffectiveOptions(config, profile, stripUnsetCliOverrides(opts, command));
-      const { policies, plugins, severityRemap } = resolvePolicyOptions(effective);
+      const cliOverrides = stripUnsetCliOverrides(opts, command);
+      const effective = resolveEffectiveOptions(config, profile, cliOverrides);
+      const { policies, plugins, severityRemap } = resolvePolicyOptions(effective, { pluginsFromCli: cliOverrides.plugins !== undefined });
       const targets = (await resolveTargetFiles(files, config)).map((f) => resolve(f));
       if (targets.length === 0) {
         throw new Error('No files matched. Provide files or configure .flectorc files/include.');
@@ -682,7 +683,8 @@ program
 
       const { config } = loadRcConfig(process.cwd());
       const profile = resolveProfileName(opts.profile);
-      const effective = resolveEffectiveOptions(config, profile, stripUnsetCliOverrides(opts, command));
+      const cliOverrides = stripUnsetCliOverrides(opts, command);
+      const effective = resolveEffectiveOptions(config, profile, cliOverrides);
       const ignorePaths = parseCsv(effective.ignore);
       const dOpts = diffOptionsFromEffective(effective, ignorePaths);
 
@@ -732,8 +734,9 @@ program
     try {
       const { config } = loadRcConfig(process.cwd());
       const profile = resolveProfileName(opts.profile);
-      const effective = resolveEffectiveOptions(config, profile, stripUnsetCliOverrides(opts, command));
-      const { policies: packIds, plugins, severityRemap } = resolvePolicyOptions(effective);
+      const cliOverrides = stripUnsetCliOverrides(opts, command);
+      const effective = resolveEffectiveOptions(config, profile, cliOverrides);
+      const { policies: packIds, plugins, severityRemap } = resolvePolicyOptions(effective, { pluginsFromCli: cliOverrides.plugins !== undefined });
 
       const limit = Number.parseInt(String(effective.limit ?? '10'), 10);
       if (!Number.isInteger(limit) || limit < 1) {
@@ -826,8 +829,9 @@ program
     try {
       const { config } = loadRcConfig(process.cwd());
       const profile = resolveProfileName(opts.profile);
-      const effective = resolveEffectiveOptions(config, profile, stripUnsetCliOverrides(opts, command));
-      const { policies: packIds, plugins, severityRemap } = resolvePolicyOptions(effective);
+      const cliOverrides = stripUnsetCliOverrides(opts, command);
+      const effective = resolveEffectiveOptions(config, profile, cliOverrides);
+      const { policies: packIds, plugins, severityRemap } = resolvePolicyOptions(effective, { pluginsFromCli: cliOverrides.plugins !== undefined });
       const targets = (await resolveTargetFiles(files, config)).map((f) => resolve(f));
       if (targets.length === 0) {
         throw new Error('No files matched. Provide files or configure .flectorc files/include.');
@@ -932,7 +936,8 @@ program
     try {
       const { config } = loadRcConfig(process.cwd());
       const profile = resolveProfileName(opts.profile);
-      const effective = resolveEffectiveOptions(config, profile, stripUnsetCliOverrides(opts, command));
+      const cliOverrides = stripUnsetCliOverrides(opts, command);
+      const effective = resolveEffectiveOptions(config, profile, cliOverrides);
       // A plan carries Terraform-shaped paths, so the config-file packs are not
       // the useful default here; `terraform` is. An explicit --policies or a
       // .flectorc entry still wins.
@@ -940,6 +945,7 @@ program
         effective.policies === undefined
           ? { ...effective, policies: PLAN_DEFAULT_POLICIES }
           : effective,
+        { pluginsFromCli: cliOverrides.plugins !== undefined },
       );
 
       const ignorePaths = parseCsv(effective.ignore);
@@ -1036,8 +1042,9 @@ program
     try {
       const { config } = loadRcConfig(process.cwd());
       const profile = resolveProfileName(opts.profile);
-      const effective = resolveEffectiveOptions(config, profile, stripUnsetCliOverrides(opts, command));
-      const { policies: packIds, plugins, severityRemap } = resolvePolicyOptions(effective);
+      const cliOverrides = stripUnsetCliOverrides(opts, command);
+      const effective = resolveEffectiveOptions(config, profile, cliOverrides);
+      const { policies: packIds, plugins, severityRemap } = resolvePolicyOptions(effective, { pluginsFromCli: cliOverrides.plugins !== undefined });
 
       const ignorePaths = parseCsv(effective.ignore);
       const failOn = parseFailOn(effective.failOn ?? 'changed,added,removed,policy,error');

package/package.json

@@ -4,7 +4,7 @@
     "access": "public",
     "provenance": true
   },
-  "version": "3.0.0",
+  "version": "3.0.1",
   "description": "Flecto \u2014 semantic config watcher that reports meaningful changes in plain English",
   "license": "MIT",
   "keywords": [

package/src/config.js

@@ -1,5 +1,5 @@
 import { existsSync, readFileSync, readdirSync, writeFileSync } from 'fs';
-import { resolve } from 'path';
+import { resolve, sep } from 'path';
 import fg from 'fast-glob';
 import yaml from 'js-yaml';
 import { isEnvFilename } from './parser.js';
@@ -80,24 +80,70 @@ export function resolveEffectiveOptions(config, profile, cliOverrides = {}) {
   return { ...defaults, ...profileOptions, ...cliOverrides };
 }
 
+/**
+ * Has the operator explicitly opted in to plugins declared in `.flectorc`?
+ * @returns {boolean}
+ */
+function rcPluginsAllowed() {
+  const raw = process.env.FLECTO_ALLOW_RC_PLUGINS;
+  return raw === '1' || String(raw).toLowerCase() === 'true';
+}
+
+/**
+ * Split a policy list that may arrive as an array or a comma-separated string.
+ * @param {unknown} raw
+ * @param {string[]} fallback
+ * @returns {string[]}
+ */
+function toList(raw, fallback) {
+  if (Array.isArray(raw)) return raw.map(String);
+  if (typeof raw === 'string') return raw.split(',').map((s) => s.trim()).filter(Boolean);
+  return fallback;
+}
+
 /**
  * Normalize policy-related effective options.
+ *
+ * Plugins execute code, and `.flectorc` is attacker-controlled on an untrusted
+ * pull request, so a plugin that came from the rc file rather than an explicit
+ * `--plugins` flag is refused unless the operator opts in with
+ * `FLECTO_ALLOW_RC_PLUGINS=1`. Refusing loudly rather than skipping silently is
+ * deliberate: a plugin that stops running without saying so would weaken a
+ * policy gate the operator believes is in place.
  * @param {Record<string, unknown>} effective
+ * @param {{ pluginsFromCli?: boolean, cwd?: string }} [provenance]
  */
-export function resolvePolicyOptions(effective) {
-  const policiesRaw = effective.policies;
-  const pluginsRaw = effective.plugins;
+export function resolvePolicyOptions(effective, provenance = {}) {
   const severityRemapRaw = effective.severityRemap;
-  const policies = Array.isArray(policiesRaw)
-    ? policiesRaw.map(String)
-    : typeof policiesRaw === 'string'
-      ? String(policiesRaw).split(',').map((s) => s.trim()).filter(Boolean)
-      : ['default'];
-  const plugins = Array.isArray(pluginsRaw)
-    ? pluginsRaw.map(String)
-    : typeof pluginsRaw === 'string'
-      ? String(pluginsRaw).split(',').map((s) => s.trim()).filter(Boolean)
-      : [];
+  const policies = toList(effective.policies, ['default']);
+  const plugins = toList(effective.plugins, []);
+
+  if (plugins.length > 0 && !provenance.pluginsFromCli) {
+    if (!rcPluginsAllowed()) {
+      throw new Error(
+        'Refusing to load policy plugins declared in .flectorc: plugins execute code, '
+        + 'and a config file can come from an untrusted pull request.\n'
+        + `Declared: ${plugins.join(', ')}\n`
+        + 'Pass them on the command line with --plugins instead, or set '
+        + 'FLECTO_ALLOW_RC_PLUGINS=1 if this config is trusted.',
+      );
+    }
+    // Opted in, but the rc file may still be attacker-authored. Keep rc-declared
+    // plugins inside the project so `../../../../tmp/x.mjs` cannot reach a module
+    // planted elsewhere on the runner. An explicit --plugins is operator intent
+    // and stays unrestricted: shared policies outside the cwd are a real setup.
+    const root = resolve(provenance.cwd ?? process.cwd());
+    for (const pluginPath of plugins) {
+      const abs = resolve(root, pluginPath);
+      if (abs !== root && !abs.startsWith(root + sep)) {
+        throw new Error(
+          `Policy plugin declared in .flectorc is outside the project: ${pluginPath}\n`
+          + 'Plugins execute code, so an rc-declared plugin must live inside the '
+          + 'directory Flecto is running in.',
+        );
+      }
+    }
+  }
   if (
     severityRemapRaw !== undefined
     && (severityRemapRaw === null || Array.isArray(severityRemapRaw) || typeof severityRemapRaw !== 'object')