Epic: Assimilate Semgrep into Ouroboros AgentOS while preserving Semgrep UX

[shaun0927]

Summary

Assimilate semgrep/semgrep into the Ouroboros plugin ecosystem as a first-class AgentOS capability while preserving the Semgrep user experience.

This epic is not about replacing Semgrep, reimplementing Semgrep, or hiding Semgrep behind a generic wrapper. The goal is to let users keep the Semgrep mental model they already know — local-first scans, familiar configs, familiar flags, JSON/SARIF output, rule testing, CI-style behavior, and optional autofix flows — while Ouroboros adds the missing AgentOS layer around it:

• explicit permissions,
• capability declarations,
• risk classification,
• audit events,
• provenance,
• normalized evidence artifacts,
• Seed / Ledger / State / Handoff compatibility,
• and resumable agent workflows.

In short:

Preserve the Semgrep experience, but make every Semgrep capability executable, inspectable, permissioned, and handoff-capable inside Ouroboros.

This directly exercises the thesis from #27:

Ouroboros plugins are not merely command wrappers. They are the capability assimilation layer that turns external tools, open-source libraries, and domain workflows into structured, auditable, permissioned, Seed-compatible Ouroboros capabilities.

Semgrep is explicitly in scope for that RFC class: a static-analysis engine that should remain outside core while becoming usable as an Ouroboros-native AgentOS capability.

Source capability

Repository: https://github.com/semgrep/semgrep

Semgrep is a mature static-analysis engine that provides:

• local code scanning,
• rule-based code search,
• security and quality guardrails,
• Semgrep YAML rules,
• JSON and SARIF outputs,
• CI-oriented scan modes,
• rule testing,
• optional registry / remote configuration,
• optional metrics,
• optional autofix / dry-run flows,
• MCP / AI-assistant integration surfaces,
• and broad language support.

Important upstream properties to preserve:

• Semgrep users expect to run scans against local repositories.
• Local scanning should remain local-first.
• Familiar Semgrep concepts such as --config, local rule files, registry configs, --json, --sarif, --metrics=off, --autofix, --dryrun, .semgrepignore, and exit-code behavior should remain recognizable.
• Semgrep output should remain available in raw form when requested.
• Ouroboros should add structured artifacts rather than erase Semgrep's native output model.

Product goal

Make Semgrep feel like a native AgentOS capability without breaking Semgrep muscle memory.

A user should be able to say, in effect:

ooo semgrep scan . --config rules/ci.yml

and get the same kind of Semgrep experience they expect, plus Ouroboros-native execution products:

Semgrep scan ran locally
Raw Semgrep JSON/SARIF was preserved
Findings were normalized
Ledger/provenance/audit records were emitted
A handoff artifact was attached
A downstream agent can now triage, fix, suppress, or gate on the results

Non-goals

This epic must not turn ouroboros-plugins into a marketplace or a dumping ground for scanner wrappers.

Out of scope for the first implementation:

• Reimplementing Semgrep's parser, rule engine, or CLI.
• Vendoring Semgrep source into this repository.
• Making Semgrep part of Ouroboros core.
• Requiring Semgrep AppSec Platform or proprietary Semgrep services.
• Uploading source code by default.
• Enabling registry/network behavior by default without explicit permission modeling.
• Enabling autofix in the v0 read-only reference path.
• Treating raw semgrep ... execution as sufficient plugin compliance.
• Adding schema fields speculatively before proving that the existing contract cannot represent the capability.

Desired plugin shape

Initial plugin candidate:

plugins/semgrep-static-analysis/
  ouroboros.plugin.json
  README.md
  semgrep_static_analysis/
    __init__.py
    __main__.py
    cli.py
    runner.py
    normalize.py
    artifacts.py
    audit.py
  tests/
    fixtures/
      semgrep-output-empty.json
      semgrep-output-findings.json
    test_normalize.py
    test_manifest.py

The name is intentionally capability-oriented rather than marketplace-oriented. Alternative names are acceptable if they preserve the same boundary:

• semgrep-static-analysis
• semgrep-code-scan
• semgrep-agentos

UX preservation contract

The plugin must preserve Semgrep UX as a hard constraint.

Preserve familiar Semgrep inputs

The plugin should accept a bounded subset of familiar Semgrep concepts first:

• target path / scanning root,
• --config with local rule files or directories,
• optional registry config only when network permission is modeled,
• include/exclude behavior where feasible,
• JSON output preservation,
• SARIF output preservation,
• metrics control,
• dry-run behavior for future autofix paths,
• Semgrep exit-code semantics where they matter for CI.

Preserve familiar Semgrep outputs

The plugin should not replace Semgrep output with only an Ouroboros summary.

It should produce:

• raw Semgrep JSON artifact,
• optional raw Semgrep SARIF artifact,
• normalized Ouroboros findings artifact,
• human-readable Markdown summary,
• audit/provenance records that point to artifact paths and hashes.

Preserve local-first behavior

The default invocation should be local and read-only:

semgrep scan --json --metrics=off --disable-version-check --config <local-config> <target>

Exact flags may vary by installed Semgrep version, but the intent must hold:

• no source upload by default,
• no registry fetch by default,
• metrics disabled by default,
• bounded repo-relative target paths,
• bounded artifact writes only into an Ouroboros-controlled output directory.

AgentOS-native translation

The plugin must translate Semgrep into Ouroboros primitives rather than merely execute it.

Core capabilities

Expected manifest capabilities for the read-only scan path:

• ledger:write — record invocation, policy inputs, scan summary, and decision-relevant facts.
• provenance:write — record Semgrep version, config source, target paths, command shape, output artifact hashes, and environment facts.
• handoff:attach — attach normalized findings and summary for downstream agents.
• progress:write — report scan progress and completion.

Optional future capabilities:

• state:write — persist scan state across resumable long-running scans or multi-stage triage.
• seed:write — generate remediation Seeds from findings when this becomes a deliberate workflow.
• runtime:execute — only if delegated agent execution becomes part of the plugin itself.

External permissions

Expected baseline permissions:

• filesystem:read / read_only / required — read target source files and local rule files.
• shell:execute / read_only / required — invoke the installed Semgrep CLI with bounded arguments.

Expected optional permissions:

• network:read / read_only / optional — only for registry configs, remote configs, version checks, or other remote Semgrep flows.
• filesystem:write / write / optional — only for future autofix or explicit artifact output outside the controlled handoff directory.

The plugin must keep capabilities and permissions distinct per #27 and docs/contract.md.

Command plan

v0 command: read-only scan

ooo semgrep scan <target-path> --config <local-config>

Responsibilities:

• validate target path is repo-relative / bounded,
• validate local config path is bounded,
• invoke Semgrep with local-first safe defaults,
• preserve raw JSON output,
• optionally preserve SARIF output if requested,
• normalize findings,
• emit audit/provenance data,
• attach handoff artifacts,
• return a clear status code / summary.

Risk: read_only

Required external permissions:

• filesystem:read
• shell:execute

Required core capabilities:

• ledger:write
• provenance:write
• handoff:attach
• progress:write

v0.1 or v1 command: CI-style scan

ooo semgrep ci-scan <target-path> --config <config> --baseline <ref>

Responsibilities:

• preserve Semgrep CI mental model,
• optionally honor baseline / changed-findings semantics,
• emit gate result suitable for ooo auto, PR review, or policy workflows,
• keep raw Semgrep output available.

Risk: usually read_only; network config must be separately declared if used.

Future command: rule test

ooo semgrep rule-test <rules-path>

Responsibilities:

• run Semgrep rule tests,
• normalize pass/fail results,
• attach rule-test evidence for plugin / policy development.

Risk: read_only

Future command: autofix dry run

ooo semgrep autofix-dryrun <target-path> --config <config>

Responsibilities:

• run Semgrep autofix in dry-run / preview mode,
• produce patch preview artifact,
• do not modify files.

Risk: read_only

Future command: autofix apply

ooo semgrep autofix <target-path> --config <config>

Responsibilities:

• apply deterministic Semgrep rule-defined fixes,
• emit patch provenance,
• attach before/after evidence,
• require explicit confirmation and filesystem:write.

Risk: write

This should not ship until the read-only scan path proves the boundary.

Manifest draft

The v0 read-only manifest should fit the current 0.1 schema without expanding the manifest contract:

{
  "schema_version": "0.1",
  "name": "semgrep-static-analysis",
  "version": "0.1.0",
  "description": "Assimilates Semgrep local static-analysis scans into Ouroboros audit, provenance, and handoff artifacts while preserving Semgrep CLI UX.",
  "source": {
    "type": "local_path",
    "path": "plugins/semgrep-static-analysis"
  },
  "commands": [
    {
      "namespace": "semgrep",
      "name": "scan",
      "summary": "Run a bounded read-only Semgrep scan and attach normalized findings as Ouroboros evidence.",
      "usage": "ooo semgrep scan <target-path> --config <local-rule-or-pack>",
      "risk": "read_only",
      "requires_confirmation": false,
      "arguments": [
        {
          "name": "target_path",
          "type": "path",
          "required": true,
          "description": "Repo-relative file or directory to scan."
        },
        {
          "name": "config",
          "type": "string",
          "required": true,
          "description": "Local Semgrep config path or explicitly approved registry config."
        }
      ]
    }
  ],
  "capabilities": [
    {
      "name": "ledger",
      "access": "write",
      "reason": "Record scan invocation, policy inputs, and summary verdict."
    },
    {
      "name": "provenance",
      "access": "write",
      "reason": "Record Semgrep version, config source, target paths, and output hashes."
    },
    {
      "name": "handoff",
      "access": "attach",
      "reason": "Attach normalized findings for downstream review or automated remediation."
    },
    {
      "name": "progress",
      "access": "write",
      "reason": "Report scan progress and completion status."
    }
  ],
  "permissions": [
    {
      "scope": "filesystem:read",
      "risk": "read_only",
      "required": true,
      "reason": "Read target source files and local Semgrep rule files."
    },
    {
      "scope": "shell:execute",
      "risk": "read_only",
      "required": true,
      "reason": "Invoke the installed Semgrep CLI with bounded arguments."
    },
    {
      "scope": "network:read",
      "risk": "read_only",
      "required": false,
      "reason": "Only needed when using Semgrep registry or remote configs."
    }
  ],
  "entrypoint": {
    "type": "command",
    "command": "python -m semgrep_static_analysis"
  },
  "audit": {
    "events": [
      "plugin.invoked",
      "plugin.permission_used",
      "plugin.completed",
      "plugin.failed"
    ]
  }
}

Artifact contract

Each successful scan should attach a handoff bundle similar to:

.omx/artifacts/semgrep/<run-id>/
  semgrep.raw.json
  semgrep.raw.sarif          # optional
  semgrep.findings.json      # normalized Ouroboros finding model
  semgrep.summary.md         # human-readable summary
  semgrep.provenance.json    # bounded provenance fields and hashes

Suggested normalized finding shape:

{
  "schema_version": "0.1",
  "tool": "semgrep",
  "tool_version": "1.x",
  "rule_id": "python.lang.security.audit...",
  "severity": "ERROR",
  "message": "...",
  "path": "src/example.py",
  "start": { "line": 10, "col": 5 },
  "end": { "line": 10, "col": 25 },
  "metadata": {
    "cwe": "...",
    "owasp": "..."
  },
  "fix_available": false,
  "fingerprint": "stable-or-derived-id",
  "raw_result_ref": "semgrep.raw.json#/results/0"
}

The normalized model should preserve enough information for downstream agents to:

• summarize risk,
• decide whether a finding blocks a workflow,
• generate remediation Seeds,
• open follow-up tasks,
• compare scan runs,
• and attach evidence to PR / review workflows.

Audit and provenance requirements

The plugin should emit / prepare audit-compatible data for:

• plugin.invoked
• plugin.permission_used
• plugin.completed
• plugin.failed

Provenance should include bounded, redacted facts only:

• Semgrep version,
• plugin version,
• command namespace/name,
• target path(s),
• config path or config identifier,
• whether config was local or remote,
• metrics mode,
• network mode,
• output artifact paths,
• artifact hashes,
• result counts by severity,
• exit code,
• run duration.

Provenance must not include:

• raw source code,
• access tokens,
• unbounded Semgrep output blobs,
• raw user prompts,
• secret values found by scans.

Privacy and network behavior

The default path must be privacy-preserving:

• prefer local config,
• set metrics off by default,
• disable version checks where feasible,
• do not fetch registry rules unless the user explicitly chooses a registry / remote config path,
• require network:read for registry or remote configuration.

If the user requests a Semgrep Registry config such as p/ci, auto, or a URL config, the plugin must surface that this is no longer a purely local invocation and requires the optional network permission path.

Dependency and license policy

Semgrep is LGPL-2.1. This repository should not vendor Semgrep source as part of the plugin.

Preferred dependency model:

1. Require an installed semgrep executable and inspect it with semgrep --version.
2. Document installation options but do not silently install Semgrep in v0.
3. Optionally support a future setup helper that installs Semgrep only after explicit user action.
4. Preserve Semgrep license notices in plugin README / docs.

This avoids turning the Ouroboros plugin into a Semgrep fork or derivative distribution problem.

Implementation phases

Phase 0 — Contract analysis and RFC alignment

• Confirm the plugin fits the current manifest schema without schema expansion.
• Document why this is an assimilation plugin, not a trivial wrapper.
• Link this epic to SSOT: UserLevel plugin authoring and capability assimilation #27 as a concrete static-analysis reference case.
• Decide final plugin name and namespace.

Phase 1 — Read-only reference plugin skeleton

• Add plugins/semgrep-static-analysis/ouroboros.plugin.json.
• Add plugin README with product boundary, non-goals, privacy behavior, and dependency expectations.
• Add Python entrypoint with scan command.
• Validate manifest with scripts/validate_contract.py.
• Add catalog entry if this repository is meant to host it as a reference plugin.

Phase 2 — Safe Semgrep runner

• Detect installed Semgrep executable.
• Capture semgrep --version.
• Build bounded argv instead of shell string interpolation.
• Enforce repo-relative / allowed target paths.
• Enforce local config by default.
• Add explicit branch for remote / registry configs requiring network:read.
• Run with metrics disabled by default.
• Preserve Semgrep exit code and stderr in bounded artifact form.

Phase 3 — Output normalization and artifacts

• Save raw Semgrep JSON.
• Optionally save raw SARIF.
• Normalize findings into an Ouroboros-friendly JSON artifact.
• Generate Markdown summary.
• Hash artifacts for provenance.
• Include result counts by severity / rule / path.

Phase 4 — Audit, provenance, and handoff

• Emit or prepare audit event payloads matching schemas/0.1/audit-event.schema.json.
• Record capabilities used.
• Record permissions used.
• Attach handoff bundle path / metadata.
• Ensure failure modes are represented as blocked or failed, not silent success.

Phase 5 — Tests and validation

• Unit-test Semgrep JSON normalization from fixtures.
• Unit-test empty findings.
• Unit-test malformed Semgrep output.
• Unit-test path bounding.
• Unit-test argv construction.
• Unit-test manifest validation.
• Run repository validator and test suite.

Phase 6 — Future UX parity expansion

• Add CI-style scan command if v0 proves the boundary.
• Add rule-test command.
• Add autofix dry-run command.
• Add autofix apply command only with filesystem:write, explicit confirmation, and patch provenance.
• Consider Semgrep MCP integration only after the CLI path is stable.

Acceptance criteria

This epic is complete when:

• A Semgrep plugin exists under plugins/<name>/ with a valid ouroboros.plugin.json.
• The plugin preserves Semgrep CLI mental model for the initial read-only scan path.
• The plugin does not vendor or reimplement Semgrep.
• The default scan path is local-first, read-only, and metrics-off.
• The manifest declares capabilities and permissions separately.
• The command risk is read_only for scan.
• Network behavior is optional and explicitly permissioned.
• Raw Semgrep JSON is preserved as an artifact.
• Normalized Ouroboros findings are produced.
• A human-readable summary is produced.
• Provenance records include Semgrep version, config source, target paths, artifact hashes, and result counts.
• Audit-compatible event payloads are generated or prepared.
• The scan result can be attached as a handoff artifact for downstream agents.
• Failure and blocked states are explicit.
• python3 scripts/validate_contract.py passes.
• Relevant unit tests pass.
• The README explains why this is an AgentOS capability assimilation plugin rather than a command wrapper.

Why this matters for AgentOS

Ouroboros becomes a true AgentOS when external tools do not merely run beside it, but become structured capabilities inside it.

Semgrep is an ideal proof case because it already has a strong developer experience and a strong CLI identity. The challenge is therefore not to redesign Semgrep. The challenge is to preserve Semgrep's UX while adding the operating-system layer that Semgrep alone does not own:

• explicit authority,
• durable state,
• auditability,
• provenance,
• normalized artifacts,
• policy-aware risk handling,
• and downstream agent handoff.

If this succeeds, the same assimilation pattern can guide future static-analysis engines, test tools, security scanners, CI gates, and remediation loops.

References

• https://github.com/semgrep/semgrep
• https://semgrep.dev/docs/getting-started/cli
• https://semgrep.dev/docs/cli-reference
• https://semgrep.dev/docs/writing-rules/rule-syntax
• https://semgrep.dev/docs/writing-rules/rule-defined-fix
• https://semgrep.dev/docs/metrics
• SSOT: UserLevel plugin authoring and capability assimilation #27

[shaun0927]

Live verification plan: Semgrep plugin in Ouroboros AgentOS

Issue #47 is merged, but the real proof should be collected at three levels. The important distinction is:

1. Plugin-level proof: the Semgrep adapter works as code.
2. AgentOS lifecycle proof: the plugin is discovered/installed/trusted/invoked through Ouroboros permission and audit boundaries.
3. End-to-end pipeline proof: a downstream agent/workflow can consume the handoff bundle and continue the work.

Below is the recommended evidence plan.

---

0. Prepare a reproducible target repo

Use a small throwaway repo so evidence is reviewable and safe:

mkdir -p /tmp/semgrep-agentos-smoke/src /tmp/semgrep-agentos-smoke/rules
cd /tmp/semgrep-agentos-smoke
git init

cat > src/example.py <<'PY'
import subprocess
subprocess.run("echo unsafe", shell=True)
PY

cat > rules/ci.yml <<'YAML'
rules:
  - id: python-dangerous-shell-true
    patterns:
      - pattern: subprocess.run(..., shell=True, ...)
    message: Avoid shell=True in subprocess calls.
    severity: ERROR
    languages: [python]
YAML

Record environment facts:

semgrep --version
python3 --version
ouroboros --version || true
ooo --version || true
git -C /path/to/ouroboros-plugins rev-parse HEAD

Evidence to save:

• terminal transcript,
• exact Semgrep version,
• exact Ouroboros/Ouroboros-plugins commit,
• target repo fixture contents.

---

1. Contract and reference-plugin proof

From a fresh ouroboros-plugins checkout on main:

pip install -r requirements-dev.txt
python3 scripts/validate_contract.py
python3 -m unittest tests/test_semgrep_static_analysis.py -v

Expected evidence:

• contract validation passed (... plugin manifest(s) validated),
• Semgrep plugin tests pass,
• manifest declares:
  • ledger:write,
  • provenance:write,
  • handoff:attach,
  • progress:write,
  • required filesystem:read,
  • required shell:execute,
  • optional network:read.

This proves the plugin fits the repository contract, but not yet that it ran through AgentOS.

---

2. Direct plugin execution smoke test

This proves the adapter can drive the installed Semgrep CLI and write the expected artifacts:

cd /path/to/ouroboros-plugins
PYTHONPATH=plugins/semgrep-static-analysis \
  python3 -m semgrep_static_analysis scan . \
  --repository-root /tmp/semgrep-agentos-smoke \
  --config rules/ci.yml \
  --output-dir .omx/artifacts/semgrep \
  --error \
  --sarif

Expected result:

• command exits with Semgrep-compatible status (1 is acceptable with --error when findings exist),
• JSON stdout includes:
  • status: success,
  • semgrep_exit_code,
  • artifact_dir,
  • finding_count,
  • handoff_path.

Expected artifact bundle:

.omx/artifacts/semgrep/<run-id>/
  semgrep.raw.json
  semgrep.raw.sarif
  semgrep.stderr.txt
  semgrep.findings.json
  semgrep.summary.md
  semgrep.provenance.json
  semgrep.audit.json
  semgrep.handoff.json

Evidence to collect:

RUN_DIR=<artifact_dir from stdout>
find "$RUN_DIR" -maxdepth 1 -type f -print | sort
cat "$RUN_DIR/semgrep.summary.md"
jq '.summary, .findings[0]' "$RUN_DIR/semgrep.findings.json"
jq '.tool, .command, .target_path, .config_kind, .network_mode, .artifacts' "$RUN_DIR/semgrep.provenance.json"
jq '.events[].event_type, .events[].permissions_used, .events[].capabilities_used, .events[].result' "$RUN_DIR/semgrep.audit.json"
jq . "$RUN_DIR/semgrep.handoff.json"
shasum -a 256 "$RUN_DIR"/*

This proves the wrapper is not merely semgrep passthrough: it preserves raw output and adds normalized findings, provenance, audit-compatible events, and handoff metadata.

---

3. Permission/privacy negative tests

These are important because #27 says plugins must be bounded capabilities, not arbitrary command wrappers.

Remote config must be blocked by default

PYTHONPATH=plugins/semgrep-static-analysis \
  python3 -m semgrep_static_analysis scan . \
  --repository-root /tmp/semgrep-agentos-smoke \
  --config p/ci

Expected:

• status: blocked,
• message says remote/registry config requires explicit network permission / --allow-remote-config,
• no remote fetch by default.

Output path must not write outside repo

PYTHONPATH=plugins/semgrep-static-analysis \
  python3 -m semgrep_static_analysis scan . \
  --repository-root /tmp/semgrep-agentos-smoke \
  --config rules/ci.yml \
  --output-dir /tmp/outside-semgrep-artifacts

Expected:

• status: blocked,
• no /tmp/outside-semgrep-artifacts directory is created by the plugin,
• blocked audit is written only to the repo-local fallback .omx/artifacts/semgrep/<run-id>/.

Config path traversal must be blocked

PYTHONPATH=plugins/semgrep-static-analysis \
  python3 -m semgrep_static_analysis scan . \
  --repository-root /tmp/semgrep-agentos-smoke \
  --config ../rules.yml

Expected:

• status: blocked,
• config must stay inside repository root.

Evidence to save:

• command stdout/stderr,
• find /tmp/semgrep-agentos-smoke/.omx/artifacts/semgrep -maxdepth 2 -type f,
• proof that outside output dir was not created.

---

4. Full Ouroboros AgentOS lifecycle proof

This is the strongest proof and should be run with an Ouroboros build that includes the plugin manager/firewall command dispatcher.

Install from the merged repository:

ouroboros plugin add https://github.com/Q00/ouroboros-plugins --plugin semgrep-static-analysis
ouroboros plugin inspect semgrep-static-analysis
ouroboros plugin trust semgrep-static-analysis --scope filesystem:read --scope shell:execute
ouroboros plugin list

Then invoke through the AgentOS command surface:

ooo semgrep scan /tmp/semgrep-agentos-smoke --config rules/ci.yml --error --sarif

If the dispatcher expects repo-relative invocation from inside the target repo, use:

cd /tmp/semgrep-agentos-smoke
ooo semgrep scan . --config rules/ci.yml --error --sarif

Expected AgentOS evidence:

• plugin was discovered/installed from Q00/ouroboros-plugins,
• trust state includes only required read-only scopes:
  • filesystem:read,
  • shell:execute,
• invocation passes the firewall,
• command risk remains read_only,
• audit shows:
  • plugin.invoked,
  • plugin.permission_used,
  • plugin.completed or plugin.failed,
• artifact bundle is attached or discoverable through handoff metadata,
• no network:read is used for local config,
• network:read is required before registry config such as p/ci is allowed.

Evidence to collect:

ouroboros plugin inspect semgrep-static-analysis --json > evidence.plugin-inspect.json || true
ouroboros plugin list --json > evidence.plugin-list.json || true
# If available in the installed core:
ouroboros ledger tail --json > evidence.ledger-tail.json || true
ooo semgrep scan . --config rules/ci.yml --error --sarif | tee evidence.ooo-semgrep.stdout.json

Also collect the produced artifact directory and hash it:

tar -czf evidence.semgrep-artifacts.tgz -C "$RUN_DIR" .
shasum -a 256 evidence.semgrep-artifacts.tgz

---

5. End-to-end AgentOS continuation proof

The handoff proof is the part that demonstrates “AgentOS pipeline”, not just plugin execution.

After ooo semgrep scan, take semgrep.handoff.json and run one downstream continuation step. Recommended options:

Option A — downstream triage prompt

Ask an agent/harness to consume only the handoff and normalized findings:

ooo auto "Triage the Semgrep handoff at <RUN_DIR>/semgrep.handoff.json. Summarize findings, decide whether this blocks merge, and propose a remediation Seed. Use only the attached artifacts as evidence."

Expected evidence:

• downstream agent reads semgrep.handoff.json,
• references semgrep.findings.json and semgrep.summary.md,
• does not need raw source upload,
• produces a triage/remediation artifact or Seed.

Option B — PR/review policy gate

Use the summary/findings as an input to an existing PR review or policy workflow:

ooo auto "Use <RUN_DIR>/semgrep.handoff.json as static-analysis evidence for a PR readiness decision. Return PASS/WARN/FAIL with cited finding fingerprints."

Expected evidence:

• decision cites normalized finding fingerprints,
• result links back to raw Semgrep JSON via raw_result_ref,
• provenance hash ties decision to immutable scan artifacts.

Option C — ledger/handoff replay

If the local Ouroboros build supports ledger replay or artifact attachment inspection, verify that the handoff can be recovered without rerunning Semgrep.

Evidence to collect:

• downstream command transcript,
• generated Seed/triage/policy artifact,
• references to finding fingerprint(s),
• proof that the downstream step consumed handoff/provenance rather than rerunning Semgrep silently.

---

6. Suggested final evidence bundle

For a complete validation report, attach or link a folder like:

evidence/semgrep-agentos-smoke/
  environment.txt
  plugin-inspect.json
  plugin-list.json
  ooo-semgrep.stdout.json
  semgrep-artifacts.tgz
  semgrep-artifacts.sha256
  semgrep.summary.md
  semgrep.findings.json
  semgrep.provenance.json
  semgrep.audit.json
  semgrep.handoff.json
  negative-remote-config.txt
  negative-output-dir.txt
  downstream-triage.md

Minimum pass criteria:

• local config scan runs without network permission,
• remote config blocks unless explicitly enabled/trusted,
• output/config/target paths are bounded,
• raw Semgrep JSON is preserved,
• normalized findings exist and include raw_result_ref, fingerprint, severity, path, and message,
• provenance includes Semgrep version, config kind, target path, artifact hashes, result counts, and exit code,
• audit-compatible events include capabilities and permissions used,
• handoff artifact can be consumed by a downstream agent/workflow,
• no source upload or Semgrep vendoring occurs.

If all of the above evidence is collected, we can say Semgrep is not only merged as a reference plugin, but is actually operating as an Ouroboros AgentOS capability in the sense intended by #27.

[shaun0927]

Reopening because full AgentOS real-world validation/evidence collection is not complete yet. Keep this epic open until end-to-end validation evidence is attached.

[shaun0927]

Current-session verification result

I ran the verification that is possible in the current Codex/OMX session and collected an evidence bundle under:

/tmp/semgrep-agentos-session-evidence-20260521T054553Z/evidence/

Environment

Captured in environment.txt:

repo=/Users/jh0927/ouroboros-plugins-issue47-semgrep
repo_head=7f1c111ce5d6420dc487303a07b3a399cc61748d
python=Python 3.14.3
semgrep=NOT_INSTALLED
ouroboros=Ouroboros version 0.38.2
ooo=NOT_INSTALLED

Important limitation: this session does not have a real semgrep binary and does not have the ooo command dispatcher installed. Therefore I could not prove a real Semgrep engine scan or ooo semgrep scan ... dispatcher invocation in this session. I did verify the available AgentOS lifecycle surface through ouroboros plugin ..., and I used a deterministic fake semgrep executable for the positive artifact/handoff path.

---

1. Ouroboros plugin lifecycle verification

Captured in ouroboros-plugin-lifecycle.txt.

Commands exercised:

ouroboros plugin discover plugins/semgrep-static-analysis
ouroboros plugin add . --plugin semgrep-static-analysis
ouroboros plugin inspect semgrep-static-analysis
ouroboros plugin trust semgrep-static-analysis --scope filesystem:read --scope shell:execute
ouroboros plugin inspect semgrep-static-analysis
ouroboros plugin list

Observed evidence:

• manifest discovery passed:
  • manifest valid: semgrep-static-analysis 0.1.0
  • commands: 1 in namespace 'semgrep'
  • capabilities: 4
  • permissions: 3
  • required scopes: filesystem:read, shell:execute
• plugin install succeeded:
  • Installed: semgrep-static-analysis 0.1.0
• before trust:
  • trust_state: installed
  • missing scopes: filesystem:read, shell:execute
• after trust:
  • trust_state: trusted
  • granted scopes: filesystem:read, shell:execute
• plugin list shows semgrep-static-analysis as trusted.

This proves the merged manifest participates in the current Ouroboros plugin lifecycle and trust model in this session.

---

2. Real dependency absence / blocked-state verification

Because semgrep is not installed in this session, I verified the plugin fails closed instead of vendoring/installing Semgrep or silently succeeding.

Command output captured in:

• real-semgrep-missing.stdout.json
• real-semgrep-missing.exit.txt

Observed result:

{
  "status": "blocked",
  "message": "Semgrep executable not found: semgrep. Install Semgrep and retry; this plugin does not vendor Semgrep.",
  "artifact_dir": ".../.omx/artifacts/semgrep/<run-id>",
  "audit_path": ".../semgrep.audit.json"
}

Exit code: 3.

This validates the dependency/license boundary: the plugin does not vendor Semgrep and reports an explicit blocked state when the external tool is unavailable.

---

3. Positive artifact/handoff path with deterministic fake Semgrep

Since real Semgrep was unavailable, I created a fake semgrep executable that mimics:

• semgrep --version,
• JSON scan output with one finding,
• SARIF output when --sarif-output is passed,
• Semgrep --error exit code behavior.

Command output captured in:

• fake-semgrep-success.stdout.json
• fake-semgrep-success.exit.txt
• artifact bundle copied to evidence files.

Observed stdout:

{
  "status": "success",
  "semgrep_exit_code": 1,
  "finding_count": 1,
  "artifact_dir": ".../.omx/artifacts/semgrep/20260521T054913Z-a9f689d8",
  "handoff_path": ".../semgrep.handoff.json"
}

Exit code: 1, intentionally preserving Semgrep --error semantics while still marking the scan artifact status as success.

Generated artifact files, captured in artifact-inventory.txt:

semgrep.audit.json
semgrep.findings.json
semgrep.handoff.json
semgrep.provenance.json
semgrep.raw.json
semgrep.raw.sarif
semgrep.stderr.txt
semgrep.summary.md

Artifact tarball/hash:

2786e7c3e24916c4a5b63fbce0c1457654212f379543e2c34b6929a7ae7d5471  semgrep-artifacts.tgz

---

4. Normalized findings / provenance / audit / handoff evidence

Captured in:

• semgrep.findings.json
• semgrep.provenance.json
• semgrep.audit.json
• semgrep.handoff.json
• artifact-json-extracts.txt

Key normalized finding evidence:

{
  "rule_id": "python-dangerous-shell-true",
  "severity": "ERROR",
  "message": "Avoid shell=True in subprocess calls.",
  "path": "src/example.py",
  "path_trust": "semgrep-reported",
  "scan_root": ".",
  "fingerprint": "3c18aac1348f483e117e5287",
  "raw_result_ref": "semgrep.raw.json#/results/0"
}

Key provenance evidence:

{
  "tool": {"name": "semgrep", "version": "1.99.0-session-fake"},
  "config": "rules/ci.yml",
  "config_kind": "local",
  "metrics": "off",
  "version_check": "disabled",
  "network_mode": "disabled",
  "exit_code": 1,
  "result_counts": {"finding_count": 1}
}

Key audit evidence:

• plugin.invoked
• plugin.permission_used
• plugin.completed

Each event included capabilities:

• ledger:write
• provenance:write
• handoff:attach
• progress:write

and permissions:

• filesystem:read
• shell:execute

Schema validation was run against the repository schemas:

manifest_schema=PASS
audit_event_0_plugin.invoked=PASS
audit_event_1_plugin.permission_used=PASS
audit_event_2_plugin.completed=PASS

---

5. Negative boundary tests

Captured in negative-tests-summary.txt.

Remote config blocked by default

Command used --config p/ci without remote opt-in.

Observed:

remote_config_exit=3
status=blocked
message=Remote or registry Semgrep configs require explicit network permission; pass --allow-remote-config after granting network:read.

Outside output dir blocked without writing outside repo

Command used --output-dir /tmp/.../outside-artifacts.

Observed:

outside_output_exit=3
outside_exists=no
status=blocked
message=output_dir must stay inside .../target

This specifically verifies the P1 fix from code review: blocked-state audit artifacts no longer create the requested outside output directory.

Config traversal blocked

Command used --config ../ci.yml.

Observed:

config_traversal_exit=3
status=blocked
message=config must stay inside .../target

---

6. Downstream handoff-readiness simulation

Captured in downstream-triage.md.

I simulated a downstream AgentOS consumer reading only the handoff/finding/provenance artifacts. The simulated triage could make a review decision and cite stable evidence:

Decision: FAIL/WARN - static analysis found 1 ERROR finding.
- fingerprint: 3c18aac1348f483e117e5287
- rule: python-dangerous-shell-true
- location: src/example.py:2:1
- raw ref: semgrep.raw.json#/results/0
- provenance network mode: disabled
- findings artifact hash: 57f9c625893eab0bf9fbe8659c07408149c8c86c727d8e8fb15d970db8760fe4

This proves the handoff bundle is shaped for downstream triage/remediation/policy-gate workflows, though not through a real ooo auto run because ooo is unavailable in this session.

---

7. Repository-level validation

Captured in:

• contract-validation.txt
• unit-tests.txt

Observed:

contract validation passed (18 plugin manifest(s) validated)
semgrep_unit_tests=PASS

The Semgrep plugin unit tests passed in this session.

---

Verdict for this session

Passed, with environment limitations.

Verified in this session:

• plugin manifest discovery,
• plugin install/trust lifecycle through ouroboros plugin,
• fail-closed behavior when real Semgrep is absent,
• deterministic scan artifact generation using a fake Semgrep executable,
• raw JSON/SARIF preservation,
• normalized findings,
• provenance and artifact hashes,
• audit-compatible event payloads,
• handoff metadata,
• negative permission/boundary behavior,
• downstream handoff-readiness by artifact consumption.

Not verified in this session:

• real Semgrep engine execution, because semgrep is not installed,
• ooo semgrep scan ... dispatcher invocation, because ooo is not installed in this session,
• full ooo auto continuation, for the same reason.

To close the remaining proof gap, run the same evidence plan in an environment with:

semgrep installed
ooo command dispatcher available
Ouroboros version with plugin command dispatch wired to `ooo semgrep scan`

Then compare the real Semgrep artifact bundle against this session's evidence shape.