{"id":45070904,"url":"https://github.com/vitas/evidra","last_synced_at":"2026-05-21T08:04:24.326Z","repository":{"id":342990574,"uuid":"1172463458","full_name":"vitas/evidra","owner":"vitas","description":"DevOps MCP server, Flight recorder for AI infrastructure agents. The prescribe/report protocol captures intent before execution and outcome after — in a signed, tamper-evident evidence chain. Detects behavioral patterns. Computes reliability scorecards.","archived":false,"fork":false,"pushed_at":"2026-05-20T17:55:55.000Z","size":8548,"stargazers_count":13,"open_issues_count":10,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-20T23:19:20.265Z","etag":null,"topics":["ai","ai-agent","audit","benchmark","ci","claude","codex","devops","evidence","evidence-chain","iac","k8s","kubernetes","mcp-server","metrics","pipeline","prescribe-report-protocol","reliability","terraform"],"latest_commit_sha":null,"homepage":"https://evidra.cc","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vitas.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":"docs/supported-tools.md","governance":"GOVERNANCE.md","roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-04T10:39:25.000Z","updated_at":"2026-05-20T17:55:59.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/vitas/evidra","commit_stats":null,"previous_names":["vitas/evidra"],"tags_count":31,"template":false,"template_full_name":null,"purl":"pkg:github/vitas/evidra","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vitas%2Fevidra","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vitas%2Fevidra/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vitas%2Fevidra/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vitas%2Fevidra/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vitas","download_url":"https://codeload.github.com/vitas/evidra/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vitas%2Fevidra/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33293466,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-21T02:57:32.698Z","status":"ssl_error","status_checked_at":"2026-05-21T02:57:31.990Z","response_time":62,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","ai-agent","audit","benchmark","ci","claude","codex","devops","evidence","evidence-chain","iac","k8s","kubernetes","mcp-server","metrics","pipeline","prescribe-report-protocol","reliability","terraform"],"created_at":"2026-02-19T12:09:55.598Z","updated_at":"2026-05-21T08:04:24.314Z","avatar_url":"https://github.com/vitas.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Evidra\n\n[![CI](https://github.com/vitas/evidra/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/vitas/evidra/actions/workflows/ci.yml)\n[![Release Pipeline](https://github.com/vitas/evidra/actions/workflows/release.yml/badge.svg?event=push)](https://github.com/vitas/evidra/actions/workflows/release.yml)\n[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n\n**Flight recorder and reliability scoring for infrastructure automation**\n\nEvidra records intent, outcome, and refusal for every infrastructure mutation — across MCP agents, CI pipelines, A2A agents, and scripts. The append-only evidence chain powers behavioral signal detection and reliability scoring. Canonicalization and risk assessment are optional external enrichments, not required core dependencies.\n\nCLI and MCP are the authoritative analytics surfaces today.\n\n**Two ways to use it:**\n\n| | What | How |\n|---|---|---|\n| **DevOps MCP Server** | All-in-one: kubectl/helm/terraform/aws with smart output + auto-evidence | `evidra-mcp` as your agent's MCP server |\n| **Flight Recorder** | Add evidence to any existing workflow — no MCP required | `evidra record`, `evidra import`, webhooks, or proxy mode |\n\n## Quick Start — MCP Server\n\n```json\n{\n  \"mcpServers\": {\n    \"evidra\": {\n      \"command\": \"evidra-mcp\",\n      \"args\": [\"--evidence-dir\", \"~/.evidra/evidence\"]\n    }\n  }\n}\n```\n\nYour agent gets seven default DevOps tools: `run_command`, `collect_diagnostics`, `write_file`, `describe_tool`, `prescribe_smart`, `report`, and `get_event`. The normal path is still `run_command` with automatic evidence recording for mutations. Use `describe_tool` only when you want the full explicit-control schema for `prescribe_smart` or `report`. Add `--full-prescribe` when you also want artifact-aware `prescribe_full`.\n\n## Quick Start — CLI (No MCP)\n\n```bash\n# Wrap any command — evidence recorded automatically\nevidra record -f deploy.yaml -- kubectl apply -f deploy.yaml\n\n# Import from CI pipelines\nevidra import --input record.json\n\n# View reliability scorecard\nevidra scorecard --period 30d\n```\n\nWorks with any agent framework, CI system, or script. No MCP required.\n\nSecurity boundary: Evidra does not sandbox the wrapped command. Treat it with the same trust model as direct shell execution.\n\n```bash\n# Install\nbrew install samebits/tap/evidra\n```\n\n## What Your Agent Gets\n\n### Smart output — fewer tokens, same information\n\n```\nAgent: run_command(\"kubectl get deployment web -n demo\")\n\n# Without evidra-mcp (raw JSON): ~2,400 tokens\n{\"apiVersion\":\"apps/v1\",\"metadata\":{\"managedFields\":[...],...},\"spec\":{...},\"status\":{...}}\n\n# With evidra-mcp (smart output): ~40 tokens\ndeployment/web (demo): 0/2 ready | image: nginx:99.99 | Available=False\n```\n\n### Auto-evidence for mutations — zero agent code\n\n```\nAgent: run_command(\"kubectl apply -f fix.yaml\")\n  → evidra auto-prescribes (intent recorded)\n  → kubectl executes\n  → evidra auto-reports (outcome recorded)\n  → smart output returned to agent\n```\n\nRead-only commands (`get`, `describe`, `logs`) execute directly — no overhead.\n\n### Skills\n\nInstall the [Evidra skill](docs/guides/skill-setup.md) to give your agent\noperational discipline: diagnosis before fix, safety boundaries, domain-specific\npatterns.\n\n### 7 default tools, plus optional Full Prescribe\n\n| Tool | Description |\n|---|---|\n| `run_command` | Execute kubectl, helm, terraform, aws — with smart output |\n| `collect_diagnostics` | Gather pods, describe output, events, and recent logs for one workload |\n| `write_file` | Write config or manifest files under the current workspace or temp directories |\n| `describe_tool` | Show the full schema for deferred protocol tools when you want explicit control |\n| `prescribe_smart` | Smart Prescribe with deferred schema loading; use `describe_tool` first when needed |\n| `report` | Record outcome; full explicit schema available via `describe_tool` |\n| `get_event` | Look up evidence |\n\nEnable `--full-prescribe` to add **Full Prescribe** when your agent has artifact bytes and you want artifact-aware explicit intent capture.\n\nMost agents only need `run_command`. Use `collect_diagnostics` when the model would otherwise spend multiple turns on `get` / `describe` / `events` / `logs`. Use `write_file` for agent-authored manifests or Terraform snippets without leaving the MCP surface. Use `describe_tool` only when you deliberately want the explicit `prescribe_smart` / `report` flow instead of the default auto-evidence path.\n\n## Why Not Just kubectl-mcp-server?\n\n| | kubectl-mcp-server | evidra-mcp |\n|---|---|---|\n| Tools | 270 specialized | 7 default tools + optional Full Prescribe |\n| Output | Raw JSON (~2400 tokens) | Smart summary (~40 tokens) |\n| Evidence | None | Auto prescribe/report for mutations |\n| Security | Open | Command allowlist + blocked subcommands |\n| Skills | None | Installable role guidance |\n| Scoring | None | Reliability scorecards + behavioral signals |\n\n## For Platform Teams\n\n### Self-hosted analytics\n\n```bash\ndocker compose up --build -d\n```\n\nCentralize evidence across agents, pipelines, and controllers:\n- Which agents retry the same operation?\n- Which scenarios cause the most failures?\n- How does model X compare to model Y on real infrastructure?\n\n### CI/CD integration\n\n```bash\n# Wrap any command — CLI records prescribe/execute/report\nevidra record -f deploy.yaml -- kubectl apply -f deploy.yaml\n\n# Import completed operations\nevidra import --input record.json\n\n# View reliability scorecard\nevidra scorecard --period 30d\n```\n\nReferences: [Self-hosted setup](docs/guides/self-hosted-setup.md) · [CLI reference](docs/integrations/cli-reference.md) · [API reference](docs/api-reference.md)\n\n## Intelligence Layer\n\nFrom the evidence chain, Evidra computes:\n\n- **Behavioral signals** — protocol violations, retry loops, blast radius, drift detection\n- **Reliability scorecards** — 0-100 score with band and confidence\n\nRisk assessment can be supplied by an external scanner or policy engine as an optional `assessment` block on prescribe entries. When no assessment is supplied, Evidra still records the intent and outcome and leaves risk fields empty.\n\nEight behavioral signals documented in the [Signal specification](docs/system-design/EVIDRA_SIGNAL_SPEC_V1.md).\n\n## Explicit Protocol (Advanced)\n\nFor agents that want full control over evidence recording:\n\n```text\nprescribe_smart / prescribe_full  →  record declared intent (+ optional canonical_action/assessment)\nexecute    →  run the command (or decline to act)\nreport     →  record verdict, exit code, or refusal reason\n```\n\nThree evidence modes:\n\n| Mode | How | Agent awareness |\n|---|---|---|\n| **Proxy Observed** | Auto prescribe/report via observed mutation-style tool calls | None needed |\n| **Smart Prescribe** | Agent calls `prescribe_smart` + `report` | Minimal (~30 tokens) |\n| **Full Prescribe** | Agent calls `prescribe_full` with artifact | Full artifact (~300 tokens) |\n\nMost users should use Proxy Observed or the default DevOps surface. Smart Prescribe and Full Prescribe are for teams\nthat want explicit prescribe/report control. If an agent needs risk context before executing, run a scanner or policy engine first and include its result as optional assessment enrichment.\n\n## Proxy Mode — Wrap Mutation-Oriented MCP Servers\n\nAdd evidence to an existing MCP server — zero agent changes:\n\n```json\n{\n  \"mcpServers\": {\n    \"infra\": {\n      \"command\": \"evidra-mcp\",\n      \"args\": [\"--proxy\", \"--\", \"npx\", \"-y\", \"@anthropic/mcp-server-kubernetes\"]\n    }\n  }\n}\n```\n\nThe proxy records evidence when it sees `run_command` or other mutation-shaped MCP tool calls it can classify heuristically. Unclassified or read-only tool calls pass through without evidence.\n\n## Docs\n\n- [MCP Setup Guide](docs/guides/mcp-setup.md)\n- [Skill Setup Guide](docs/guides/skill-setup.md)\n- [CLI Reference](docs/integrations/cli-reference.md)\n- [API Reference](docs/api-reference.md)\n- [Architecture](docs/system-design/EVIDRA_ARCHITECTURE_V1.md)\n- [Protocol Specification](docs/system-design/EVIDRA_PROTOCOL_V1.md)\n- [Scoring Rationale](docs/system-design/scoring/default.v1.1.0.md)\n- [MCP Registry Publication Guide](docs/guides/mcp-registry-publication.md)\n- [Supported Tools](docs/supported-tools.md)\n\n## Development\n\n```bash\nmake build\nmake test\nmake lint\nmake test-mcp-inspector    # MCP protocol compliance tests\n```\n\n### Environment Variables\n\n| Variable | Description |\n|---|---|\n| `EVIDRA_EVIDENCE_DIR` | Evidence storage path (default: `~/.evidra/evidence`) |\n| `EVIDRA_SIGNING_MODE` | `strict` (default) or `optional` (dev mode) |\n| `EVIDRA_SIGNING_KEY` | Base64 Ed25519 signing key |\n| `EVIDRA_ENVIRONMENT` | Environment label (production, staging) |\n\n## License\n\nLicensed under the [Apache License 2.0](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvitas%2Fevidra","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvitas%2Fevidra","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvitas%2Fevidra/lists"}