@cirvix_ai/agent-control 0.1.0

package/action/action.yml

@@ -0,0 +1,134 @@
+# Cirvix — scan a repository for ungoverned AI agents.
+#
+# Published as `cirvix/scan`. A composite action rather than a JavaScript one,
+# deliberately: a JS action ships a committed `dist/` bundle that has to be
+# rebuilt on every change and is, in practice, the thing that goes stale. The
+# CLI has zero runtime dependencies, so `npx` is a smaller and more honest
+# supply chain than a vendored bundle nobody re-reads.
+name: Cirvix AgentControl Scan
+description: Find AI agent runtimes, MCP servers, and reachable credentials that nothing is governing.
+author: Cirvix
+
+branding:
+  icon: shield
+  color: green
+
+inputs:
+  fail-on:
+    description: >-
+      Fail the job at this severity or above: high, medium, or low. Set to
+      "never" to report without failing — the right setting for the first run
+      on an existing repository, where the point is to see the baseline rather
+      than to block a merge on it.
+    required: false
+    default: high
+  working-directory:
+    description: Directory to scan. Defaults to the workspace root.
+    required: false
+    default: .
+  sarif-file:
+    description: Where to write SARIF. Set to an empty string to skip.
+    required: false
+    default: cirvix-scan.sarif
+  upload-sarif:
+    description: >-
+      Upload findings to GitHub code scanning, so they appear on the pull
+      request diff and in the Security tab rather than only in this log.
+      Requires `security-events: write`.
+    required: false
+    default: "true"
+  comment-on-pr:
+    description: Write the summary as a pull-request comment as well as a job summary.
+    required: false
+    default: "false"
+  version:
+    description: Version of @cirvix_ai/agent-control to run.
+    required: false
+    default: latest
+
+outputs:
+  high:
+    description: Number of high-severity findings.
+    value: ${{ steps.scan.outputs.high }}
+  medium:
+    description: Number of medium-severity findings.
+    value: ${{ steps.scan.outputs.medium }}
+  low:
+    description: Number of low-severity findings.
+    value: ${{ steps.scan.outputs.low }}
+  findings:
+    description: The full scan result as JSON.
+    value: ${{ steps.scan.outputs.findings }}
+  passed:
+    description: "true when nothing at or above `fail-on` was found."
+    value: ${{ steps.scan.outputs.passed }}
+
+runs:
+  using: composite
+  steps:
+    - name: Run Cirvix scan
+      id: scan
+      shell: bash
+      working-directory: ${{ inputs.working-directory }}
+      env:
+        CIRVIX_FAIL_ON: ${{ inputs.fail-on }}
+        CIRVIX_SARIF: ${{ inputs.sarif-file }}
+        CIRVIX_VERSION: ${{ inputs.version }}
+      run: |
+        set -euo pipefail
+
+        args=(--json)
+        if [ -n "${CIRVIX_SARIF}" ]; then
+          args+=(--sarif "${CIRVIX_SARIF}")
+        fi
+
+        # The scan's exit code is the signal, and `set -e` would take the job
+        # down before the summary is written. Captured, reported, then
+        # re-raised at the end by the reporter.
+        set +e
+        npx --yes "@cirvix_ai/agent-control@${CIRVIX_VERSION}" scan "${args[@]}" > cirvix-scan.json
+        scan_status=$?
+        set -e
+
+        if [ "${scan_status}" -ne 0 ] && [ ! -s cirvix-scan.json ]; then
+          echo "::error title=Cirvix::The scan did not run. Check that @cirvix_ai/agent-control@${CIRVIX_VERSION} exists."
+          exit 1
+        fi
+
+        node "${GITHUB_ACTION_PATH}/report.mjs" cirvix-scan.json
+
+    - name: Upload SARIF to code scanning
+      # `always()` so a failing scan still uploads. Findings that only appear
+      # when the build passes are findings nobody acts on.
+      if: ${{ always() && inputs.upload-sarif == 'true' && inputs.sarif-file != '' }}
+      continue-on-error: true
+      uses: github/codeql-action/upload-sarif@v3
+      with:
+        sarif_file: ${{ inputs.working-directory }}/${{ inputs.sarif-file }}
+        category: cirvix
+
+    - name: Comment on the pull request
+      if: ${{ always() && inputs.comment-on-pr == 'true' && github.event_name == 'pull_request' }}
+      continue-on-error: true
+      shell: bash
+      working-directory: ${{ inputs.working-directory }}
+      env:
+        GH_TOKEN: ${{ github.token }}
+      run: |
+        set -euo pipefail
+        if [ -f cirvix-summary.md ]; then
+          # `--edit-last` so a pushed branch updates one comment instead of
+          # accumulating a thread nobody reads to the bottom of.
+          gh pr comment "${{ github.event.pull_request.number }}" \
+            --body-file cirvix-summary.md --edit-last --create-if-none
+        fi
+
+    - name: Enforce the severity gate
+      if: ${{ always() && inputs.fail-on != 'never' }}
+      shell: bash
+      working-directory: ${{ inputs.working-directory }}
+      run: |
+        if [ "${{ steps.scan.outputs.passed }}" != "true" ]; then
+          echo "::error title=Cirvix::Findings at or above '${{ inputs.fail-on }}'. See the job summary."
+          exit 1
+        fi

package/action/report.mjs

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+/**
+ * Turns a scan result into things a reviewer will actually see.
+ *
+ * Three surfaces, because a CI log is not one of them: a job summary somebody
+ * reads without expanding a step, inline annotations on the pull request, and
+ * step outputs so a workflow can branch on the numbers.
+ *
+ * Zero dependencies, like everything else that ships. An action that pulls a
+ * markdown library to build a table is an action with a supply chain.
+ */
+
+import { appendFile, readFile, writeFile } from "node:fs/promises";
+
+const SEVERITY_ORDER = { high: 0, medium: 1, low: 2 };
+const GATE = { high: ["high"], medium: ["high", "medium"], low: ["high", "medium", "low"] };
+const ICON = { high: "🔴", medium: "🟠", low: "🟡" };
+
+const [, , resultPath] = process.argv;
+
+const result = JSON.parse(await readFile(resultPath ?? "cirvix-scan.json", "utf8"));
+const findings = [...(result.findings ?? [])].sort(
+  (a, b) => SEVERITY_ORDER[a.severity] - SEVERITY_ORDER[b.severity],
+);
+const counts = result.counts ?? {};
+const high = counts.high ?? 0;
+const medium = counts.medium ?? 0;
+const low = counts.low ?? 0;
+
+const failOn = (process.env.CIRVIX_FAIL_ON ?? "high").toLowerCase();
+const watched = GATE[failOn] ?? [];
+const blocking = watched.reduce((n, level) => n + (counts[level] ?? 0), 0);
+const passed = failOn === "never" || blocking === 0;
+
+/* -- annotations ----------------------------------------------------------- */
+
+// Only the blocking ones. Annotating every low finding on every pull request
+// is how a team learns to scroll past the annotations, which costs more than
+// the low findings were worth.
+for (const finding of findings.filter((f) => watched.includes(f.severity))) {
+  const level = finding.severity === "high" ? "error" : "warning";
+  const title = `Cirvix: ${finding.subject}`;
+  const body = `${finding.detail}${finding.fix ? `  Fix: ${finding.fix}` : ""}`;
+  // GitHub's annotation format takes no newlines; %0A is the documented escape.
+  process.stdout.write(
+    `::${level} title=${escapeProperty(title)}::${escapeData(body)}\n`,
+  );
+}
+
+/* -- summary --------------------------------------------------------------- */
+
+const verdict = passed
+  ? high + medium + low === 0
+    ? "Nothing ungoverned found."
+    : `No findings at or above **${failOn}**.`
+  : `**${blocking}** finding${blocking === 1 ? "" : "s"} at or above **${failOn}**.`;
+
+const lines = [
+  "## Cirvix AgentControl",
+  "",
+  verdict,
+  "",
+  `| ${ICON.high} High | ${ICON.medium} Medium | ${ICON.low} Low |`,
+  "|---|---|---|",
+  `| ${high} | ${medium} | ${low} |`,
+  "",
+];
+
+if (findings.length) {
+  lines.push(
+    "| | Finding | What it means | Fix |",
+    "|---|---|---|---|",
+    ...findings
+      .slice(0, 40)
+      .map(
+        (f) =>
+          `| ${ICON[f.severity] ?? ""} | \`${escapeCell(f.subject)}\` | ${escapeCell(f.detail)} | ${
+            f.fix ? `\`${escapeCell(f.fix)}\`` : "—"
+          } |`,
+      ),
+  );
+  // Silence about truncation reads as "that was all of them".
+  if (findings.length > 40) {
+    lines.push("", `_${findings.length - 40} further findings are in the SARIF upload._`);
+  }
+} else {
+  lines.push(
+    "No agent runtime, MCP server, or reachable credential in this repository is currently ungoverned.",
+  );
+}
+
+lines.push(
+  "",
+  `<sub>Scanned ${result.cwd ?? "."} at ${result.scannedAt ?? "unknown time"}. `,
+  "Findings describe what an agent *could* reach, not what one has done. ",
+  "Nothing was executed and no code was sent anywhere.</sub>",
+);
+
+const summary = lines.join("\n");
+
+if (process.env.GITHUB_STEP_SUMMARY) {
+  await appendFile(process.env.GITHUB_STEP_SUMMARY, summary + "\n", "utf8");
+}
+// Written unconditionally so the pull-request comment step has it whether or
+// not a summary file exists — a local run of this script is a supported way to
+// see what CI would say.
+await writeFile("cirvix-summary.md", summary + "\n", "utf8");
+
+/* -- outputs --------------------------------------------------------------- */
+
+await setOutput("high", String(high));
+await setOutput("medium", String(medium));
+await setOutput("low", String(low));
+await setOutput("passed", String(passed));
+await setOutput("findings", JSON.stringify(result));
+
+process.stdout.write(`\n${verdict.replace(/\*\*/g, "")}\n`);
+
+/* -------------------------------------------------------------------------- */
+
+async function setOutput(name, value) {
+  if (!process.env.GITHUB_OUTPUT) return;
+  // A multi-line value has to use the delimiter form, and the delimiter has to
+  // be one the value cannot contain — otherwise a finding containing the
+  // delimiter string can inject arbitrary outputs into the workflow.
+  const delimiter = `cirvix_${Math.random().toString(36).slice(2)}_${Date.now().toString(36)}`;
+  await appendFile(
+    process.env.GITHUB_OUTPUT,
+    `${name}<<${delimiter}\n${value}\n${delimiter}\n`,
+    "utf8",
+  );
+}
+
+function escapeData(value) {
+  return String(value).replace(/%/g, "%25").replace(/\r/g, "%0D").replace(/\n/g, "%0A");
+}
+
+function escapeProperty(value) {
+  return escapeData(value).replace(/:/g, "%3A").replace(/,/g, "%2C");
+}
+
+function escapeCell(value) {
+  return String(value).replace(/\|/g, "\\|").replace(/\n/g, " ");
+}