raes 0.25.0__tar.gz

raes-0.25.0/.gitignore

@@ -0,0 +1,223 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# Local research and working notes
+/research/
+/notes/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer,
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Claude local scheduler state
+.claude/scheduled_tasks.lock
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+.codex
+
+# Ground Control transient tool output (sonar analysis cache, step telemetry).
+# .gc/plan-rules.md and other authored .gc files stay tracked.
+.gc/sonar/
+.gc/telemetry/
+
+# OSV-scanner advisory report (generated by the `osv_scan` nox session; issue #34).
+implementations/python/osv-scanner-report.json

raes-0.25.0/PKG-INFO

@@ -0,0 +1,290 @@
+Metadata-Version: 2.4
+Name: raes
+Version: 0.25.0
+Summary: Backend-agnostic cyber range scenario description language and runtime.
+Requires-Python: >=3.11
+Requires-Dist: asyncssh>=2.23.0
+Requires-Dist: blake3<2,>=1.0.8
+Requires-Dist: cryptography>=46.0.7
+Requires-Dist: defusedxml>=0.7.1
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: packaging>=23.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rfc8785<0.2,>=0.1.4
+Requires-Dist: rich>=13.0.0
+Requires-Dist: sse-starlette>=2.0.0
+Requires-Dist: typer>=0.12.0
+Requires-Dist: uvicorn[standard]>=0.34.0
+Requires-Dist: z3-solver==4.16.0.0
+Provides-Extra: dev
+Requires-Dist: coverage>=7.0.0; extra == 'dev'
+Requires-Dist: httpx>=0.27.0; extra == 'dev'
+Requires-Dist: hypothesis>=6.0.0; extra == 'dev'
+Requires-Dist: pytest-cov>=7.1.0; extra == 'dev'
+Requires-Dist: pytest-mock>=3.12.0; extra == 'dev'
+Requires-Dist: pytest-timeout>=2.4.0; extra == 'dev'
+Requires-Dist: pytest-xdist>=3.8.0; extra == 'dev'
+Requires-Dist: pytest>=9.0.3; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: furo>=2024.5.6; extra == 'docs'
+Requires-Dist: myst-parser>=3.0.0; extra == 'docs'
+Requires-Dist: sphinx-autobuild>=2024.4.16; extra == 'docs'
+Requires-Dist: sphinx-copybutton>=0.5.2; extra == 'docs'
+Requires-Dist: sphinx>=7.3.0; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# Reproducible Agentic Environments System
+
+Reproducible Agentic Environments System (RAES) is a backend-agnostic scenario
+description language, Python reference implementation, and contract surface
+for cyber range scenarios and experiments.
+
+The repository separates authored scenario meaning from processors, backends,
+participant implementations, runtime state, and archived evidence. In the
+current implementation, an SDL document can be parsed, validated,
+instantiated, compiled into runtime models, and checked against published
+backend contracts without binding the authored scenario 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 reference implementation code, not treated as a product
+surface.
+
+The repository is not a managed cyber range and does not include a production
+backend. Backend contracts, stubs, conformance checks, and examples are present;
+real deployment backends remain separate implementations.
+
+A worked example of RAES SDL driving a concrete range is
+[APTL (Advanced Purple Team Lab)](https://github.com/Brad-Edwards/aptl), a
+separate project that specifies its scenarios as RAES SDL documents and
+realizes the selected topology on a Docker Compose backend.
+
+## Contents
+
+- [What RAES Describes](#what-raes-describes)
+- [Getting Started](#getting-started)
+- [Using the Python Reference Implementation](#using-the-python-reference-implementation)
+- [Repository Layout](#repository-layout)
+- [Lineage](#lineage)
+- [Documentation](#documentation)
+- [Verification](#verification)
+- [Contributing](#contributing)
+- [Versioning](#versioning)
+- [Citation](#citation)
+- [License](#license)
+- [Maintainer](#maintainer)
+
+## What RAES 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.
+
+```yaml
+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/`](https://github.com/RAESystem/rae/tree/main/examples/scenarios).
+Reusable non-normative templates and patterns are indexed by
+[`examples/library/catalog.yaml`](https://github.com/RAESystem/rae/blob/main/examples/library/catalog.yaml).
+
+## Getting Started
+
+Prerequisites:
+
+- Python 3.11 or newer
+- [uv](https://github.com/astral-sh/uv)
+- [nox](https://nox.thea.codes/) for the repository verification graph, or
+  `uvx nox` without a separate install
+
+Set up the Python reference implementation:
+
+```shell
+git clone https://github.com/RAESystem/rae.git
+cd rae/implementations/python
+uv sync --all-extras
+uv run raes --help
+```
+
+## Using the Python Reference Implementation
+
+Parse and validate a scenario from Python:
+
+```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`:
+
+```shell
+uv run raes sdl resolve ../../examples/scenarios/hospital-ransomware-surgery-day.sdl.yaml
+uv run raes sdl verify-imports ../../examples/scenarios/hospital-ransomware-surgery-day.sdl.yaml
+uv run raes sdl publish ../../examples/scenarios/hospital-ransomware-surgery-day.sdl.yaml
+uv run raes processor --help
+uv run raes conformance --help
+uv run raes-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 plus reusable authoring templates and patterns
+- `docs/` - explanatory documentation, API docs, and architecture decisions
+- `research/` - supporting literature and reference ecosystem material
+- `tools/` - repository maintenance, policy, and publication tooling
+
+## Lineage
+
+- [Open Cyber Range SDL](https://documentation.opencyberrange.ee/docs/sdl/reference/)
+- [Open Cybersecurity Schema Framework](https://schema.ocsf.io/)
+- [CACAO Security Playbooks v2.0](https://docs.oasis-open.org/cacao/security-playbooks/v2.0/security-playbooks-v2.0.html)
+- [STIX 2.1](https://docs.oasis-open.org/cti/stix/v2.1/stix-v2.1.html)
+- [CybORG](https://github.com/cage-challenge/CybORG)
+- [TENA](https://www.trmc.osd.mil/tena-about.html)
+- [IEEE High Level Architecture](https://standards.ieee.org/standard/1516-2025.html)
+- [SISO Cyber DEM](https://cdn.ymaws.com/www.sisostandards.org/resource/resmgr/standards_products/siso-std-025-2023_cyberdem.pdf)
+- [SISO Cyber FOM](https://www.sisostandards.org/news/690125/Publication-of-Cyber-FOM-and-SIRL-Users-Guide.htm)
+- [MITRE CALDERA](https://github.com/mitre/caldera)
+- [Atomic Red Team](https://github.com/redcanaryco/atomic-red-team)
+
+For a dimension-by-dimension comparison against these systems — what RAES
+expresses that they do not, and where they still lead RAES — see
+[Related-Work Comparison](https://github.com/RAESystem/rae/blob/main/docs/explain/sdl/related-work-comparison.md).
+
+## Documentation
+
+The documentation source is under [`docs/`](https://github.com/RAESystem/rae/tree/main/docs). Important entry points:
+
+- [`docs/index.md`](https://github.com/RAESystem/rae/blob/main/docs/index.md) - documentation index
+- [`docs/explain/getting-started.md`](https://github.com/RAESystem/rae/blob/main/docs/explain/getting-started.md) - use-case and rigor-level entrypoint
+- [`docs/migration/raes-rename.md`](https://github.com/RAESystem/rae/blob/main/docs/migration/raes-rename.md) - RAES rename hard-cutover map
+- [`examples/README.md`](https://github.com/RAESystem/rae/blob/main/examples/README.md) - current worked example inventory
+- [`examples/library/catalog.yaml`](https://github.com/RAESystem/rae/blob/main/examples/library/catalog.yaml) - template and pattern library catalog
+- [`docs/explain/reference/canonical-reference-map.md`](https://github.com/RAESystem/rae/blob/main/docs/explain/reference/canonical-reference-map.md) - current reference map
+- [`docs/explain/reference/documentation-style-guide.md`](https://github.com/RAESystem/rae/blob/main/docs/explain/reference/documentation-style-guide.md) - documentation style and citation rules
+- [`docs/explain/reference/glossary.md`](https://github.com/RAESystem/rae/blob/main/docs/explain/reference/glossary.md) - current terminology
+- [`docs/explain/sdl/index.md`](https://github.com/RAESystem/rae/blob/main/docs/explain/sdl/index.md) - SDL guide
+- [`docs/explain/sdl/runtime-architecture.md`](https://github.com/RAESystem/rae/blob/main/docs/explain/sdl/runtime-architecture.md) - runtime architecture
+- [`docs/explain/reference/backend-conformance.md`](https://github.com/RAESystem/rae/blob/main/docs/explain/reference/backend-conformance.md) - backend conformance model
+- [`docs/decisions/adrs/README.md`](https://github.com/RAESystem/rae/blob/main/docs/decisions/adrs/README.md) - architecture decisions
+- [`contracts/README.md`](https://github.com/RAESystem/rae/blob/main/contracts/README.md) - contract publication surface
+
+## Verification
+
+`nox` is the canonical verification graph. From the repository root:
+
+```shell
+uvx nox -s verify
+uvx nox -s verify-changed
+uvx nox -s tests
+uvx nox -l
+```
+
+The full `verify` session is unconditional and runs the project checks expected
+for pull requests, including repository policy, governed evidence and generated
+artifacts, parallel worker-safe test coverage, serial integration tests, and
+docs. Use `verify-changed` while iterating: it compares the branch and working
+tree with the upstream ref, skips evidence and regression stages only for
+allowlisted prose or research-only changes, and fails closed to the full local
+gate for unknown, deleted, renamed, executable, contract, or configuration
+changes. The pre-push hook uses the same change-aware plan.
+
+Whole-scenario finite-domain satisfiability can be inspected without applying
+or provisioning a scenario:
+
+```shell
+uv run --project implementations/python raes processor satisfiability \
+  path/to/scenario.sdl.yaml \
+  --profile aces-finite-domain-satisfiability-v1
+```
+
+The command emits the published replayable evidence envelope. Exit `0` is a
+completed satisfiable or unsatisfiable analysis, `2` is an explicit unsupported
+fragment result, and `1` is an input or operational failure. See ADR-086 for the
+bounded target coverage and nonclaims.
+
+## Contributing
+
+Contributions are welcome where they improve the language, reference
+implementation, contracts, tests, examples, or documentation. Start with
+[CONTRIBUTING.md](https://github.com/RAESystem/rae/blob/main/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 version lives in
+[`implementations/python/pyproject.toml`](https://github.com/RAESystem/rae/blob/main/implementations/python/pyproject.toml)
+and is bumped by [release-please](https://github.com/googleapis/release-please)
+from the Conventional Commit history on `main`, which also generates
+`CHANGELOG.md`. Do not hand-edit the version or `CHANGELOG.md`. See
+[`docs/explain/releasing.md`](https://github.com/RAESystem/rae/blob/main/docs/explain/releasing.md).
+
+Published JSON Schemas use versioned contract identifiers such as
+`sdl-authoring-input-v1`, but the suffix is not the same as a stability promise.
+The authoritative schema publication index assembles independent per-contract
+records, each carrying its schema's `draft` or `stable` stability class and
+canonical content hash. Current checked-in schemas
+are draft until a maintainer explicitly promotes them; stable breaking changes
+must mint a new schema version as described in
+[ADR-061](https://github.com/RAESystem/rae/blob/main/docs/decisions/adrs/adr-061-published-schema-evolution-policy.md).
+
+## Maintainers
+
+- Brad Edwards — [Personal GitHub](https://github.com/Brad-Edwards), [PANW GitHub](https://github.com/Brad-Edwards-SecOps), [LinkedIn](https://www.linkedin.com/in/bradley-edwards-dev/)
+
+## Citation
+
+If you use RAES SDL in academic work, cite the repository:
+
+```bibtex
+@software{raes,
+  author       = {Edwards, Brad},
+  title        = {RAES SDL: Backend-Agnostic Scenario Description Language for Cyber Range Experiments},
+  year         = {2026},
+  license      = {MIT},
+  url          = {https://github.com/RAESystem/rae}
+}
+```
+
+## License
+
+Released under the MIT License. See [LICENSE](https://github.com/RAESystem/rae/blob/main/LICENSE).
+Third-party attribution and license notices are recorded in
+[THIRD_PARTY_NOTICES.md](https://github.com/RAESystem/rae/blob/main/THIRD_PARTY_NOTICES.md).