Metadata-Version: 2.4
Name: raes-env-packs
Version: 3.1.0
Summary: RAES environment-pack definition, schemas, template, and authoring/validation tooling.
Project-URL: Homepage, https://github.com/RAESystem/env-packs
Project-URL: Repository, https://github.com/RAESystem/env-packs
Author: Brad Edwards
License: MIT
License-File: LICENSE
Keywords: cyber-range,environment-pack,raes,security
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Security
Requires-Python: >=3.11
Requires-Dist: pyyaml>=6
Requires-Dist: raes==2.0.0
Description-Content-Type: text/markdown

# RAES Environment Packs

[![PyPI](https://img.shields.io/pypi/v/raes-env-packs)](https://pypi.org/project/raes-env-packs/)
[![Python](https://img.shields.io/pypi/pyversions/raes-env-packs)](https://pypi.org/project/raes-env-packs/)
[![Documentation](https://app.readthedocs.org/projects/env-packs/badge/?version=latest)](https://env-packs.readthedocs.io/en/latest/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/RAESystem/env-packs/badge)](https://scorecard.dev/viewer/?uri=github.com/RAESystem/env-packs)
[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/13833/badge)](https://www.bestpractices.dev/projects/13833)

RAES environment packs give a scenario a standard shape. This package defines that
shape and gives you the tools to build, check, and ship a pack.

A pack holds the declarative content for one reference environment: the scenario
start state, its assets, and a record of where the content came from. Authors
build packs; consumers validate a pack before they trust it. The format and the
tools ship together, so you validate a pack against the same version you built it
against.

This repository defines and validates the format. It does not host packs — those
live in their own catalog repositories.

## What a pack looks like

```
example-pack/
├── pack.yaml                  # identity: name, title, version, status
├── sdl/example.sdl.yaml       # the scenario start state (RAES SDL)
└── docs/
    └── provenance-ledger.yaml # where the content came from
```

The start state is small to begin with:

```yaml
name: example-pack
nodes:
  target:
    type: vm
```

## Install

```sh
pip install raes-env-packs
```

That installs four command-line tools and the importable library:

- `raes-new-pack` — scaffold a new pack from the bundled template.
- `raes-pack-validate` — the author-CI check for a catalog checkout.
- `raes-pack-release` — build, lint, and release-gate a pack.
- `raes-pack-issue-skeleton` — generate a pack's starter GitHub issues.

## Validate your first pack

Scaffold a pack in your catalog repository, add a start state, and check it:

```sh
raes-new-pack example-pack --title "Example Pack" \
  --description "A tiny example environment pack." --issue 1
# add sdl/example.sdl.yaml (above) and set the pack name in
# docs/provenance-ledger.yaml, then:
python -c "from raes_env_packs import validate_pack; print(validate_pack('environments/example-pack').ok)"
```

```
True
```

`validate_pack` is the check a consumer runs before trusting a pack: it reads the
staged files, returns a result, prints nothing, and never runs the pack's code.
The [quickstart](https://env-packs.readthedocs.io/en/latest/quickstart.html) walks
through it step by step.

## Choose your route

- **Author a pack** — start with the [quickstart](https://env-packs.readthedocs.io/en/latest/quickstart.html)
  and the [pack reference](https://env-packs.readthedocs.io/en/latest/environment-packs.html).
- **Consume a pack** — see [validating a pack](https://env-packs.readthedocs.io/en/latest/validating.html).
- **Contribute** — read [CONTRIBUTING.md](CONTRIBUTING.md).

Full documentation is on [Read the Docs](https://env-packs.readthedocs.io/en/latest/).

## What this is and is not

This project defines the pack format and the tools that check it. It does **not**
host packs, run a scenario, or define scenario meaning — the RAES scenario
language and its semantics belong to [RAES](https://github.com/RAESystem/rae), and
this project consumes them from an exactly pinned `raes` release. It is a
single-maintainer project with no support SLA. See the
[limitations](https://env-packs.readthedocs.io/en/latest/limitations.html) for the
full picture.

## Contributing

```sh
python3 -m venv .venv
. .venv/bin/activate
pip install -e .
python -m unittest discover -s tests
```

[CONTRIBUTING.md](CONTRIBUTING.md) has the full setup, test, and submission path.
Maintainer records — decision records, CI, and release mechanics — are indexed in
[docs/README.md](docs/README.md).

## Releases

Releases are managed by [release-please](https://github.com/googleapis/release-please):
merge-driven, nothing hand-run. Your **Conventional Commit PR title** is the
release decision — `feat:` is a minor bump, `fix:` a patch, `docs:`/`chore:` no
release. You never edit the version or `CHANGELOG.md`; release-please owns both.
See [CONTRIBUTING.md](CONTRIBUTING.md#releases) for the details.

## License

MIT — see [LICENSE](LICENSE).
