Getting Started¶

This guide walks you through the core concepts of ACES and how to get involved.

What is ACES?¶

ACES (Automated Compliance Evidence Standard) is a protocol specification — not a product. It defines:

1. How compliance evidence is structured (JSON schema)
2. How evidence maps to framework controls (control mapping tables)
3. How compliance scores are calculated (scoring model)
4. How AI tools query evidence via MCP (MCP protocol)

You can implement ACES in any language, tool, or platform.

Reading the Specification¶

Start here, in order:

1. Core Concepts — vocabulary and mental model
2. Evidence Schema — the data structure
3. Control Mapping — linking evidence to frameworks
4. Scoring Model — how scores are calculated
5. MCP Protocol — the AI-native query interface

A Minimal Evidence Object¶

{
  "aces_version": "0.1",
  "id": "ev_01JNKXAMPLE",
  "collected_at": "2026-03-22T00:00:00Z",
  "tenant": {
    "company_id": "msp-acme",
    "client_id": "client-acme-corp"
  },
  "connector": {
    "connector_type_id": "sentinelone",
    "last_sync_status": "success"
  },
  "evidence_type": "endpoint_protection",
  "description": "EDR agent active on 98% of endpoints",
  "control_mappings": [
    { "framework": "cis-v8",      "control_id": "10.1" },
    { "framework": "cmmc-level2", "control_id": "SI.1.210" }
  ],
  "metrics": [
    {
      "category": "endpoint_protection",
      "metric_key": "agents_online_percentage",
      "metric_value": "98.0",
      "metric_type": "percentage",
      "unit": "%"
    }
  ]
}

Ways to Contribute¶

• Propose schema changes — open a GitHub issue or discussion
• Add framework mappings — submit a PR with a new mapping table
• Build an implementation — build a tool that produces or consumes ACES evidence
• Review the spec — read a section and open issues for anything unclear

See Contributing for full details.