stageflow 0.25.0 → 0.27.0

package/examples/compliance-review-demo/README.md

@@ -0,0 +1,125 @@
+# compliance-review-demo
+
+A demo of a Stageflow pipeline built for unattended, scheduled compliance
+checking. A SOC2-style bucket public-access check is the working example —
+the point is the *pattern*: connect, poll, check, map to a control, log
+evidence, publish a report, safe to run on a cron schedule with nobody
+watching. It runs against a real AWS S3 bucket, a real GCS bucket, or a
+simulated fixture, whichever `poll-bucket-config` finds available.
+
+Verified end to end against a real GCS bucket — see [Verified against real
+infra](#verified-against-real-infra) below for the actual run data.
+
+## What this demonstrates
+
+- **Never blocks, still tells the difference.** `review-verdict.yaml` reads
+  the checked-in evidence log and compares this run's verdict to the last
+  one recorded for the same check. A first-time failure or a repeat result
+  gets `reviewer: "auto"`. A flip (FAIL → PASS or back) gets
+  `reviewer: "unreviewed-flip"` instead — same non-blocking success either
+  way, so nothing about a schedule or a CI runner can get this stage stuck
+  waiting on a person. The distinction lives in the evidence, not in a gate.
+- **State that persists across runs.** `store-evidence.yaml` appends to a
+  checkout file (`data/evidence-log.json`, gitignored — see below) instead
+  of a per-attempt artifact, so `review-verdict` can compare "this run"
+  against "last run" days or weeks apart. `store-evidence.yaml` carries an
+  after-phase `verify` check (`type: checkout_changes`,
+  `path_fields: [changed_files]`) so the stage can't succeed without a real
+  edit to that file.
+- **One report stage, swappable target.** `publish-report.yaml` writes a
+  markdown timeline as a stage artifact today. Point that same stage at a
+  Confluence or Notion API instead and nothing upstream of it changes —
+  the other six stages don't know or care where the report ends up.
+
+Full design writeup (why this exists instead of just running Prowler in a
+GitHub Action, or self-hosting an existing open-source tool like Comp AI):
+see the project conversation this came from.
+
+## Prerequisites
+
+- Node.js ≥ 20, Stageflow installed (`npm i -g stageflow`)
+- A configured provider (`sf providers status`; at least one row
+  `configured`)
+- No cloud account needed — without a working `gcloud` or `aws` CLI on
+  PATH, `poll-bucket-config` simulates the check instead, clearly labeled
+  as simulated.
+
+### Testing against a real bucket
+
+`poll-bucket-config` tries `gcloud` first, then `aws`, then falls back to
+simulated. To point it at a real bucket:
+
+- **GCS**: have `gcloud` authenticated (`gcloud auth list` shows an active
+  account) and pass that bucket's bare name (no `gs://`) as `bucket` in the
+  task input. It reads `public_access_prevention` and
+  `uniform_bucket_level_access` from `gcloud storage buckets describe`, and
+  checks `gcloud storage buckets get-iam-policy` for any `allUsers` /
+  `allAuthenticatedUsers` binding. `scenario` is ignored in this path — the
+  bucket's real state decides the verdict, so to see a flip you need to
+  actually change the bucket's settings between runs (e.g. toggle uniform
+  bucket-level access), not just change `scenario`.
+- **AWS S3**: have `aws` authenticated and pass the bucket name; it calls
+  `aws s3api get-public-access-block` directly, same field names.
+
+The four fields it maps to (`block_public_acls`, `ignore_public_acls`,
+`block_public_policy`, `restrict_public_buckets`) are cloud-agnostic — for
+GCS they're a translation, not a literal setting name, and the stage writes
+both the raw `gcloud` fields and the translated ones to its artifact so the
+mapping is never hidden.
+
+## Commands
+
+From the **repository git root**:
+
+```bash
+sf validate --pipeline examples/compliance-review-demo/compliance-review-demo.pipeline.yaml --strict
+```
+
+Use the `stageflow-run` job to build a task with a payload like
+`{ "bucket": "customer-uploads", "scenario": "fail" }`, or point `sf run`
+at it directly:
+
+```bash
+sf run \
+  --pipeline examples/compliance-review-demo/compliance-review-demo.pipeline.yaml \
+  --task <path> \
+  --json
+```
+
+Never pauses, so it's safe to call from a non-interactive runner — a
+nightly GitHub Action, a Cloud Scheduler → Cloud Run job, an EventBridge
+Scheduler → Fargate task, or any cron.
+
+## Verified against real infra
+
+This pipeline has actually been run, twice, against a live GCS bucket, via
+a Stageflow MCP host on a different checkout than the pipeline files
+themselves (`task.checkout` pointed it at this worktree). Real, unrounded
+per-stage cost from that first run:
+
+| Stage | Cost (USD) |
+|---|---|
+| connect-account | $0.0213894 |
+| poll-bucket-config | $0.0505455 |
+| run-compliance-check | $0.0361527 |
+| review-verdict | $0.0325805 |
+| map-to-control | $0.0246600 |
+| store-evidence | $0.0451638 |
+| publish-report | $0.0480890 |
+| **Total** | **$0.2585808** |
+
+Run 1: bucket had `public_access_prevention: inherited`,
+`uniform_bucket_level_access: false` → verdict `FAIL`, `reviewer: "auto"`
+(first observation, nothing to flip against). The bucket was then actually
+hardened (`gcloud storage buckets update --uniform-bucket-level-access`,
+`--pap`) and reverted afterward. Run 2 against the hardened bucket: verdict
+`PASS`, `reviewer: "unreviewed-flip"` — logged as a flip worth a human's
+attention, without the run ever pausing to ask for one.
+
+## Data directory is gitignored
+
+`data/evidence-log.json` is runtime output written by `store-evidence`, not
+source, and in practice ends up referencing whatever real bucket and
+project someone tested against. It's gitignored on purpose — don't remove
+that `.gitignore` to "fix" an empty `data/` directory after a fresh clone;
+the file is created on first run.

package/examples/compliance-review-demo/compliance-review-demo.pipeline.yaml

@@ -0,0 +1,29 @@
+id: compliance-review-demo
+stages:
+  - id: connect-account
+    uses: ./connect-account.yaml
+    entry: true
+    route:
+      - to: poll-bucket-config
+  - id: poll-bucket-config
+    uses: ./poll-bucket-config.yaml
+    route:
+      - to: run-compliance-check
+  - id: run-compliance-check
+    uses: ./run-compliance-check.yaml
+    route:
+      - to: review-verdict
+  - id: review-verdict
+    uses: ./review-verdict.yaml
+    route:
+      - to: map-to-control
+  - id: map-to-control
+    uses: ./map-to-control.yaml
+    route:
+      - to: store-evidence
+  - id: store-evidence
+    uses: ./store-evidence.yaml
+    route:
+      - to: publish-report
+  - id: publish-report
+    uses: ./publish-report.yaml

package/examples/compliance-review-demo/connect-account.yaml

@@ -0,0 +1,47 @@
+id: connect-account
+system_prompt: |
+  This pipeline demonstrates Stageflow orchestrating a compliance check with
+  a human-in-the-loop review gate. A SOC2-style bucket public-access check is
+  the example — the point of this pipeline is the orchestration pattern, not
+  compliance coverage. It works against a real AWS S3 bucket, a real GCS
+  bucket, or a simulated fixture — whichever the next stage finds available.
+
+  State the scope for this run: read-only access to bucket configuration
+  only (no write or delete permissions), and the target bucket. Read
+  optional "bucket" and "scenario" fields from the task's input object.
+  Default bucket to "customer-uploads" and scenario to "fail" when absent.
+  scenario must end up "fail" or "fixed" — if the task gave something else,
+  use "fail". scenario is only used as a fallback if no real cloud CLI is
+  available; it's ignored entirely when polling a real bucket.
+
+  This stage does not call AWS or GCP itself — it only records the scope
+  and scenario the next stage will use.
+
+  Write a short artifact via write_stage_artifact naming the bucket, check,
+  and scenario.
+
+  summary and payload are handed to the next stage verbatim. State outcomes
+  and artifact pointers only. Do not repeat this stage's prohibitions in
+  summary — downstream will obey them literally.
+
+  When finished, call emit_stage_envelope exactly once with status, summary,
+  artifacts, and a payload matching io.output.schema: bucket, check_id
+  ("bucket-public-access-block"), and scenario. Your last tool call in this
+  attempt must be emit_stage_envelope. An empty final message is a stage
+  failure.
+model: anthropic/claude-sonnet-4-5
+io:
+  input:
+    schema:
+      type: object
+  output:
+    schema:
+      type: object
+      required: [bucket, check_id, scenario]
+      properties:
+        bucket:
+          type: string
+        check_id:
+          type: string
+        scenario:
+          type: string

package/examples/compliance-review-demo/map-to-control.yaml

@@ -0,0 +1,123 @@
+id: map-to-control
+system_prompt: |
+  Read verdict, check_id, resource, reviewed, auto_approved, and reviewer
+  from the prior stage's payload.
+
+  Map check_id "bucket-public-access-block" to SOC2 control
+  "CC6.1 — logical access is restricted", regardless of which cloud the
+  bucket lives in. This demo hardcodes one mapping; a real build would look
+  this up from a maintained check-to-control table (Prowler ships one for
+  its AWS checks; a GCP-equivalent would need its own).
+
+  summary and payload are handed to the next stage verbatim. State outcomes
+  and artifact pointers only. Do not repeat this stage's prohibitions in
+  summary — downstream will obey them literally.
+
+  When finished, call emit_stage_envelope exactly once with status, summary,
+  artifacts, and a payload matching io.output.schema: everything carried
+  forward from the prior stage, plus control_id = "CC6.1". Your last tool
+  call in this attempt must be emit_stage_envelope. An empty final message
+  is a stage failure.
+model: anthropic/claude-sonnet-4-5
+io:
+  input:
+    schema:
+      type: object
+      required:
+        - bucket
+        - check_id
+        - scenario
+        - source
+        - block_public_acls
+        - ignore_public_acls
+        - block_public_policy
+        - restrict_public_buckets
+        - verdict
+        - resource
+        - failed_fields
+        - reviewed
+        - auto_approved
+        - reviewer
+      properties:
+        bucket:
+          type: string
+        check_id:
+          type: string
+        scenario:
+          type: string
+        source:
+          type: string
+        block_public_acls:
+          type: boolean
+        ignore_public_acls:
+          type: boolean
+        block_public_policy:
+          type: boolean
+        restrict_public_buckets:
+          type: boolean
+        verdict:
+          type: string
+        resource:
+          type: string
+        failed_fields:
+          type: array
+          items:
+            type: string
+        reviewed:
+          type: boolean
+        auto_approved:
+          type: boolean
+        reviewer:
+          type: string
+  output:
+    schema:
+      type: object
+      required:
+        - bucket
+        - check_id
+        - scenario
+        - source
+        - block_public_acls
+        - ignore_public_acls
+        - block_public_policy
+        - restrict_public_buckets
+        - verdict
+        - resource
+        - failed_fields
+        - reviewed
+        - auto_approved
+        - reviewer
+        - control_id
+      properties:
+        bucket:
+          type: string
+        check_id:
+          type: string
+        scenario:
+          type: string
+        source:
+          type: string
+        block_public_acls:
+          type: boolean
+        ignore_public_acls:
+          type: boolean
+        block_public_policy:
+          type: boolean
+        restrict_public_buckets:
+          type: boolean
+        verdict:
+          type: string
+        resource:
+          type: string
+        failed_fields:
+          type: array
+          items:
+            type: string
+        reviewed:
+          type: boolean
+        auto_approved:
+          type: boolean
+        reviewer:
+          type: string
+        control_id:
+          type: string

package/examples/compliance-review-demo/poll-bucket-config.yaml

@@ -0,0 +1,103 @@
+id: poll-bucket-config
+system_prompt: |
+  Read bucket, check_id, and scenario from the prior stage's payload.
+  bucket is the bare bucket name, no gs:// or s3:// prefix — add the right
+  prefix yourself for whichever CLI you end up using.
+
+  The four output fields (block_public_acls, ignore_public_acls,
+  block_public_policy, restrict_public_buckets) are cloud-agnostic — they
+  mean "is public access meaningfully blocked", not literally AWS S3
+  setting names. Try real polls in this order, first one that works wins:
+
+  1. GCP: if `gcloud` is on PATH and `gcloud auth list
+     --filter=status:ACTIVE --format="value(account)"` returns a account,
+     poll the real bucket:
+       gcloud storage buckets describe gs://<bucket> --format=json
+       gcloud storage buckets get-iam-policy gs://<bucket> --format=json
+     Read these exact fields from the describe output:
+       public_access_prevention  ("enforced" or "inherited")
+       uniform_bucket_level_access  (boolean)
+     From the IAM policy output, check every binding's members list for
+     "allUsers" or "allAuthenticatedUsers" — call this has_public_iam_binding.
+     Map to the four fields:
+       block_public_acls    = uniform_bucket_level_access
+       ignore_public_acls   = uniform_bucket_level_access
+       block_public_policy  = (public_access_prevention == "enforced")
+       restrict_public_buckets = NOT has_public_iam_binding
+     Set source = "real-gcp". Ignore scenario in this case.
+
+  2. AWS: else if `aws` CLI is on PATH and `aws sts get-caller-identity`
+     succeeds, run `aws s3api get-public-access-block --bucket <bucket>`
+     and use that real response directly (the field names already match).
+     Set source = "real-aws". Ignore scenario in this case.
+
+  3. Simulated: otherwise — no working cloud CLI — produce a SIMULATED
+     response and set source = "simulated". Never present simulated data
+     as real; label it "simulated" wherever it's written down. Use
+     scenario to pick the fixture:
+
+       scenario "fail":
+         { block_public_acls: true, ignore_public_acls: true,
+           block_public_policy: false, restrict_public_buckets: true }
+
+       scenario "fixed":
+         { block_public_acls: true, ignore_public_acls: true,
+           block_public_policy: true, restrict_public_buckets: true }
+
+  Write the raw response via write_stage_artifact. For a real GCP poll,
+  include both the raw gcloud fields (public_access_prevention,
+  uniform_bucket_level_access, has_public_iam_binding) and the four mapped
+  booleans, so the translation is visible, not hidden. Clearly mark the
+  artifact "simulated", "real-aws", or "real-gcp".
+
+  summary and payload are handed to the next stage verbatim. State outcomes
+  and artifact pointers only. Do not repeat this stage's prohibitions in
+  summary — downstream will obey them literally.
+
+  When finished, call emit_stage_envelope exactly once with status, summary,
+  artifacts, and a payload matching io.output.schema: bucket, check_id,
+  scenario carried forward, plus source and the four boolean fields. Your
+  last tool call in this attempt must be emit_stage_envelope. An empty
+  final message is a stage failure.
+model: anthropic/claude-sonnet-4-5
+io:
+  input:
+    schema:
+      type: object
+      required: [bucket, check_id, scenario]
+      properties:
+        bucket:
+          type: string
+        check_id:
+          type: string
+        scenario:
+          type: string
+  output:
+    schema:
+      type: object
+      required:
+        - bucket
+        - check_id
+        - scenario
+        - source
+        - block_public_acls
+        - ignore_public_acls
+        - block_public_policy
+        - restrict_public_buckets
+      properties:
+        bucket:
+          type: string
+        check_id:
+          type: string
+        scenario:
+          type: string
+        source:
+          type: string
+        block_public_acls:
+          type: boolean
+        ignore_public_acls:
+          type: boolean
+        block_public_policy:
+          type: boolean
+        restrict_public_buckets:
+          type: boolean

package/examples/compliance-review-demo/publish-report.yaml

@@ -0,0 +1,79 @@
+id: publish-report
+system_prompt: |
+  Read the evidence log at
+  examples/compliance-review-demo/data/evidence-log.json (checkout-relative,
+  use the Read tool) and the current run's payload.
+
+  Write a short markdown report via write_stage_artifact (for example
+  report.md) showing the timeline for this check_id + resource: every
+  recorded verdict with its timestamp, and — for any row with
+  reviewed = true — the reviewer. Make the human-in-the-loop review visible:
+  call out explicitly which rows were auto-approved (no flip) versus which
+  required a person's confirmation (a flip), since that distinction is the
+  whole point of this pipeline.
+
+  When finished, call emit_stage_envelope exactly once with status, summary,
+  and artifacts pointing at the report. Your last tool call in this attempt
+  must be emit_stage_envelope. An empty final message is a stage failure.
+model: anthropic/claude-sonnet-4-5
+io:
+  input:
+    schema:
+      type: object
+      required:
+        - bucket
+        - check_id
+        - scenario
+        - source
+        - block_public_acls
+        - ignore_public_acls
+        - block_public_policy
+        - restrict_public_buckets
+        - verdict
+        - resource
+        - failed_fields
+        - reviewed
+        - auto_approved
+        - reviewer
+        - control_id
+        - changed_files
+      properties:
+        bucket:
+          type: string
+        check_id:
+          type: string
+        scenario:
+          type: string
+        source:
+          type: string
+        block_public_acls:
+          type: boolean
+        ignore_public_acls:
+          type: boolean
+        block_public_policy:
+          type: boolean
+        restrict_public_buckets:
+          type: boolean
+        verdict:
+          type: string
+        resource:
+          type: string
+        failed_fields:
+          type: array
+          items:
+            type: string
+        reviewed:
+          type: boolean
+        auto_approved:
+          type: boolean
+        reviewer:
+          type: string
+        control_id:
+          type: string
+        changed_files:
+          type: array
+          items:
+            type: string
+  output:
+    schema:
+      type: object

package/examples/compliance-review-demo/review-verdict.yaml

@@ -0,0 +1,122 @@
+id: review-verdict
+system_prompt: |
+  This stage never pauses for a human — it has to be safe to run unattended
+  on a schedule (cron, a nightly GitHub Action, Cloud Scheduler). It still
+  tells the difference between "nothing changed" and "this just flipped,"
+  it just never blocks on that difference.
+
+  1. Read examples/compliance-review-demo/data/evidence-log.json if it
+     exists (checkout-relative path, use the Read tool). Find the most
+     recent entry for this run's check_id + resource, if any.
+  2. No prior entry, or the prior entry's verdict matches this run's
+     verdict: set reviewer = "auto".
+  3. Prior entry exists and its verdict differs from this run's verdict (a
+     flip): set reviewer = "unreviewed-flip" and write a short artifact via
+     write_stage_artifact noting the flip (prior verdict, new verdict, the
+     raw field values from the prior stage's payload), so a person can spot
+     it later in the evidence log or the published report — without the
+     run ever waiting on them.
+  4. In both cases set reviewed = false and auto_approved = true. Never
+     call ask_operator — this stage has no gate_kinds. Always emit an
+     advancing success status; a flip is information, not a failure.
+
+  summary and payload are handed to the next stage verbatim. State outcomes
+  and artifact pointers only. Do not repeat this stage's prohibitions in
+  summary — downstream will obey them literally.
+
+  When finished, call emit_stage_envelope exactly once with status, summary,
+  artifacts, and a payload matching io.output.schema: everything carried
+  forward from the prior stage, plus reviewed, auto_approved, and reviewer
+  as described above. Your last tool call in this attempt must be
+  emit_stage_envelope. An empty final message is a stage failure.
+model: anthropic/claude-sonnet-4-5
+io:
+  input:
+    schema:
+      type: object
+      required:
+        - bucket
+        - check_id
+        - scenario
+        - source
+        - block_public_acls
+        - ignore_public_acls
+        - block_public_policy
+        - restrict_public_buckets
+        - verdict
+        - resource
+        - failed_fields
+      properties:
+        bucket:
+          type: string
+        check_id:
+          type: string
+        scenario:
+          type: string
+        source:
+          type: string
+        block_public_acls:
+          type: boolean
+        ignore_public_acls:
+          type: boolean
+        block_public_policy:
+          type: boolean
+        restrict_public_buckets:
+          type: boolean
+        verdict:
+          type: string
+        resource:
+          type: string
+        failed_fields:
+          type: array
+          items:
+            type: string
+  output:
+    schema:
+      type: object
+      required:
+        - bucket
+        - check_id
+        - scenario
+        - source
+        - block_public_acls
+        - ignore_public_acls
+        - block_public_policy
+        - restrict_public_buckets
+        - verdict
+        - resource
+        - failed_fields
+        - reviewed
+        - auto_approved
+        - reviewer
+      properties:
+        bucket:
+          type: string
+        check_id:
+          type: string
+        scenario:
+          type: string
+        source:
+          type: string
+        block_public_acls:
+          type: boolean
+        ignore_public_acls:
+          type: boolean
+        block_public_policy:
+          type: boolean
+        restrict_public_buckets:
+          type: boolean
+        verdict:
+          type: string
+        resource:
+          type: string
+        failed_fields:
+          type: array
+          items:
+            type: string
+        reviewed:
+          type: boolean
+        auto_approved:
+          type: boolean
+        reviewer:
+          type: string