Skip to content

index.md

Latest commit

 

History

History
117 lines (100 loc) · 6.15 KB

index.md

File metadata and controls

117 lines (100 loc) · 6.15 KB
Raw

Coding Ethos Docs

coding-ethos is policy as code for AI coding agents. It turns a repository's engineering principles into generated agent instructions, CEL policy checks, Git hooks, MCP tools, SARIF output, runtime sandbox evidence, and CI gates.

Current OpenSSF Best Practices status: Silver. Gold readiness and remaining gaps are tracked in the OpenSSF Gold checklist.

coding-ethos MCP and SARIF demo

Start Here

  • README: project overview, quick start, supported agents, and common workflows.
  • Repository analysis: source-of-truth boundaries, generated artifacts, and verification model.
  • Strategic roadmap: major platform directions for MCP, CEL, SARIF, sandboxing, and agent remediation loops.
  • Capability surface decision guide: routing rules for choosing CEL/policy/hooks, generated skills, MCP, CLI, SARIF/code-intel/outputsurface, or provider registries.
  • AST/CEL/SARIF architecture: the preferred path for turning parsed source facts into principle-owned CEL policy, stable SARIF, and code-intelligence storage.
  • Code intelligence: local DuckDB, duckdb-vss, Tree-sitter chunks, SARIF/remediation evidence, and MCP retrieval surfaces.
  • Agent proxy foundation: opt-in proxy trust boundary, provider-neutral event envelope, code-intel ledger, CEL facts, SARIF properties, and operator model.
  • Trust signals: OpenSSF Scorecard, Best Practices badge, security posture, and publication checklist.
  • OpenSSF Gold checklist: .bestpractices.json evidence, remaining Gold gaps, and remediation plan.
  • Security assurance case: security claims, evidence, input-validation posture, and known limits.
  • Gold security posture: cryptography applicability, TLS verification, site hardening, and release signing.
  • Build reproducibility: repeatable build inputs, deterministic Go flags, generated artifact checks, and known limits.
  • Supply-chain attestations: Scorecard publishing, GitHub artifact provenance, SBOMs, PyPI Trusted Publishing, checksums, and verification commands.
  • Threat model: protected assets, actors, trust boundaries, risks, and out-of-scope claims.
  • Release process: versioning, artifact, checklist, and release note expectations.
  • Discussions plan: recommended GitHub Discussions categories and issue/discussion boundaries.
  • Demo: verified MCP, command-block, lint-check, and SARIF excerpts plus a recording plan.
  • Comparison: how coding-ethos relates to pre-commit, CodeQL, Semgrep, OPA, branch protection, and plain agent instructions.
  • Integrations: Codex, Claude Code, Gemini CLI, MCP, GitHub Actions, GitLab CI, SARIF consumers, and managed static analysis.

AI Agent Policy Enforcement

coding-ethos is built for agentic development workflows where Codex, Claude Code, Gemini CLI, and human contributors need the same enforceable rules.

  • Capability surface decision guide: choose the owning public surface before adding new agent-facing capabilities.
  • MCP server: stdio MCP tools for policy checks, lint advice, SARIF remediation, risk summaries, and capability inspection.
  • Code intelligence: MCP-backed search over stored SARIF, remediation outcomes, hook traces, Tree-sitter chunks, and vector metadata.
  • Integrations: setup notes for Codex, Claude Code, Gemini CLI, MCP clients, GitHub Actions, GitLab CI, SARIF consumers, and managed tools.
  • Provider capability matrix: generated adapter support, partial-support, unsupported-surface, MCP, memory, and verification coverage by provider.
  • Runtime sandboxing: native namespaces, cgroups, seccomp, network isolation, and least-privilege tool capabilities.
  • Red-team suite: adversarial coverage for hook bypass, shell parsing, protected paths, MCP framing, SARIF, and sandbox behavior.

CEL Policy Language

CEL lets repos express narrow custom policies without adding a new Go evaluator for every rule. Principle-owned CEL policies live with the ETHOS principle they enforce.

  • Policy language strategy: CEL inputs, helper functions, staged migration path, and limits.
  • AST/CEL/SARIF architecture: source-fact collection, CEL evaluation, SARIF emission, and code-intel persistence.
  • MCP server: policy explanation and policy check tools that expose compiled CEL behavior to agents.

SARIF And Code Scanning

SARIF turns local policy and static-analysis evidence into code-scanning, artifact, trend, and remediation workflows.

  • CI/CD SARIF: generated GitHub Actions and GitLab CI gates.
  • SARIF uses: remediation advice, risk summaries, trend analysis, editor loops, and policy feedback.
  • SARIF editor integration: local workflows for developers and agents.
  • Code intelligence: persistent SARIF and AST-backed retrieval for repeated-failure analysis and remediation memory.

Hook And Tool Runtime

  • Hook runtime bootstrap: checkout-local runtime artifacts, repair behavior, and consumer hook entrypoints.
  • Runtime publication: PyPI generator boundaries and the release-asset model for future compiled Go runtime distribution.
  • Lint capture Go flow: managed lint capture through compiled Go request, target resolution, config validation, and normalized output.
  • Source docs index: full document list for maintainers.