Agentic Cyber Environment System

Agentic Cyber Environment System (ACES) is a backend-agnostic scenario description language and reference runtime for cyber range scenarios and experiments.

The repository separates authored scenario meaning from processors, backends, participant implementations, runtime state, and archived evidence. That lets the same scenario be validated and compiled without binding it to one cloud, range implementation, or execution harness.

This is an academic and engineering project. The repository is intended to be read, tested, and used as a working reference implementation, not treated as a product surface.

Contents

• What ACES SDL Describes
• Getting Started
• Using the Python Reference Implementation
• Repository Layout
• Lineage
• Documentation
• Verification
• Contributing
• Versioning
• Citation
• License
• Maintainer

What ACES SDL Describes

An SDL file is a declarative scenario document. It can describe topology, hosts, services, identities, content, relationships, agents, objectives, workflows, variables, and evaluation material without directly describing a specific backend's infrastructure primitives.

name: hospital-ransomware-surgery-day
description: Surgery-day ransomware exercise for a regional hospital.

variables:
  surgery_day_speed:
    type: number
    default: 1.0

nodes:
  internet-edge:
    type: Switch
    description: Public ingress for email, VPN, and external access

  mail-gateway:
    type: VM
    os: linux
    source: secure-mail-gateway
    resources: {ram: 2 gib, cpu: 1}
    services:
      - {port: 25, name: smtp-inbound}
    roles: {mail-admin: postfix}

Complete examples live in examples/scenarios/.

Getting Started

Prerequisites:

• Python 3.11 or newer
• uv
• nox for the repository verification graph, or uvx nox without a separate install

Set up the Python reference implementation:

git clone https://github.com/autarchy-ai/aces.git
cd aces/implementations/python
uv sync --all-extras
uv run aces --help

Using the Python Reference Implementation

Parse and validate a scenario from Python:

from pathlib import Path

from aces_sdl import parse_sdl_file

scenario = parse_sdl_file(
    Path("../../examples/scenarios/hospital-ransomware-surgery-day.sdl.yaml")
)

for advisory in scenario.advisories:
    print(advisory)

Run the CLI from implementations/python:

uv run aces sdl resolve ../../examples/scenarios/hospital-ransomware-surgery-day.sdl.yaml
uv run aces sdl verify-imports ../../examples/scenarios/hospital-ransomware-surgery-day.sdl.yaml
uv run aces sdl publish ../../examples/scenarios/hospital-ransomware-surgery-day.sdl.yaml
uv run aces processor --help
uv run aces conformance --help
uv run aces-mcp

Repository Layout

• specs/ - normative prose and formal specification material
• contracts/ - published schemas, fixtures, manifests, and profiles
• implementations/ - reference implementations and their local tooling
• examples/ - worked SDL scenario examples
• docs/ - explanatory documentation, API docs, and architecture decisions
• research/ - supporting literature and reference ecosystem material
• tools/ - repository maintenance, policy, and publication tooling
• changelog.d/ - towncrier release note fragments

Lineage

• Open Cyber Range SDL
• Open Cybersecurity Schema Framework
• CACAO Security Playbooks v2.0
• STIX 2.1
• CybORG
• TENA
• IEEE High Level Architecture
• SISO Cyber DEM
• SISO Cyber FOM
• MITRE CALDERA
• Atomic Red Team

Documentation

The documentation source is under docs/. Important entry points:

• docs/index.md - documentation index
• docs/explain/sdl/index.md - SDL guide
• docs/explain/sdl/runtime-architecture.md - runtime architecture
• docs/explain/reference/backend-conformance.md - backend conformance model
• docs/decisions/adrs/README.md - architecture decisions
• contracts/README.md - contract publication surface

Verification

nox is the canonical verification graph. From the repository root:

uvx nox -s verify
uvx nox -s tests
uvx nox -l

The full verify session runs the project checks expected for pull requests, including repository policy, generated artifact checks, tests, and docs.

Contributing

Contributions are welcome where they improve the language, reference implementation, contracts, tests, examples, or documentation. Start with CONTRIBUTING.md.

Language and contract changes should be discussed before implementation because small SDL changes can affect validation, generated schemas, backend conformance, and existing scenario examples.

Versioning

The Python package currently declares its version in implementations/python/pyproject.toml. Release notes are collated from towncrier fragments in changelog.d/. Do not hand-edit CHANGELOG.md.

Maintainers

• Brad Edwards — Personal GitHub, PANW GitHub, LinkedIn

Citation

If you use ACES SDL in academic work, cite the repository:

@software{aces_sdl,
  author       = {Edwards, Brad},
  title        = {ACES SDL: Backend-Agnostic Scenario Description Language for Cyber Range Experiments},
  year         = {2026},
  organization = {Autarchy},
  license      = {MIT},
  url          = {https://github.com/autarchy-ai/aces}
}

License

Released under the MIT License. See LICENSE.