Metadata-Version: 2.5
Name: aesn
Version: 0.1.0
Summary: Enterprise AIOps and State Machine Engine
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: fastapi>=0.100.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: uvicorn>=0.22.0
Description-Content-Type: text/markdown

# AESN

AESN is a program that runs a list of computer commands one at a time and writes a signed record of what actually happened. The list is called a plan. A plan names each command to be executed and states a rule for what arguments that command is permitted to use. AESN will not execute a command whose arguments violate its rule, and will not execute any later command once an earlier command fails. After the plan finishes, AESN writes a transcript that names every command that ran, records that command's exit status and a hash of its output, and notes how long each command took. AESN signs the transcript with a cryptographic key, so a party holding the corresponding public key can confirm the transcript has not been altered since it was written.

AESN is an abbreviation for Assured Execution and Signing Node. The four words name four functions: *Assured* refers to the runner's refusal of any command whose arguments fall outside its declared rule; *Execution* refers to the ordered running of commands; *Signing* refers to the Ed25519 signature over the transcript; *Node* refers to AESN's place as one program in a larger verification set.


AESN is a standalone program. No other program from The Mark Intelligence Group's stack is required to install, configure, or run AESN. AESN belongs to The Mark Intelligence Group's stack in the sense that the programs in the stack share a design: each occupies a distinct layer, each is independently installable, and no program imports or communicates with any other program at runtime. The relationship is described under "Relationship to The Mark Intelligence Group's stack" at the end of this document.

## What problem AESN solves

The Mark Intelligence Group's stack produces eight independent kinds of
verifiable claim about a computer system. AESN contributes the fourth: a
signed record of which commands ran, in which order, under which argument
rules, and with which outputs.

AESN's claim is the input to every other claim in the stack. The states
that tstate enumerates are states that some command brought the system
into. The files that state-substrate attests are files that some command
wrote. The model that twin-fabric compares against a system is a model of
a system that some command operated on. Without a signed record of which
commands ran, every other claim in the stack rests on the assumption that
the system was in some known configuration when the claim was made.

AESN's purpose within the stack is to close that assumption. The program
takes a written list of commands — the plan — and executes the commands
in order, refusing any command whose arguments fall outside a declared
rule, and stopping the plan on the first failure. After the plan finishes,
AESN writes a transcript listing every command that ran, the exit status
of each command, a hash of each command's output, and the time each
command took. AESN signs the transcript with an Ed25519 key.

AESN's importance within the stack is that AESN produces the one artifact
that says what the system actually did, as opposed to what the system's
files, models, or attestations say about what it could or should do. A
verifier holding the public key can check the transcript offline, without
trusting the machine that ran the plan.

## What AESN provides

Three components:

- **Plans.** A plan is a JSON file with three sections: a list of operations, an ordering constraint between operations, and a scope block declaring which arguments each operation type is permitted to receive.
- **A runner.** The runner reads a plan, verifies that the operations form a directed acyclic graph, verifies that every operation's argument is within the declared scope, and executes the operations in topological order. A failing operation stops the plan. An out-of-scope argument is refused before any subprocess is spawned.
- **A signer.** After the plan completes, the runner writes a transcript file containing each operation, its exit status, hashes of its output, and its duration. The transcript is signed with an Ed25519 key.

## The three operation types

The current version ships with three operation types:

- `pytest` — runs a Python test suite at a given path. The scope rule states which paths the operation is permitted to test.
- `psql` — issues a SQL statement against a PostgreSQL database. The scope rule states that only statements whose first word is `SELECT` are permitted. Statements starting with INSERT, UPDATE, DELETE, DROP, TRUNCATE, ALTER, or GRANT are rejected before a database connection is opened.
- `curl` — fetches an HTTP or HTTPS URL. The scope rule states which hostnames the operation is permitted to reach. URLs with other schemes (`file://`, `ftp://`) are rejected.

## Installation

    pip install asf-engine

The command installs AESN and its one runtime dependency, the `cryptography` library. The command does not install any other program from The Mark Intelligence Group's stack. AESN does not require any other program from The Mark Intelligence Group's stack to be present.

Requires Python 3.12 or newer.

Installing the entire The Mark Intelligence Group's stack requires eight separate `pip install` commands, one per program. A list of all eight, with each program's package name and one-sentence description, is maintained in [tmig/docs/INSTALL.md](https://github.com/Danny-TMIG/tmig/blob/main/docs/INSTALL.md).

## A first plan

The following file is a complete plan. The file is named `plan.json`.

    {
      "operations": [
        {"type": "pytest", "args": "tests/"}
      ],
      "order": [],
      "scope": {"pytest": ["tests/"]}
    }

The plan contains one operation. The operation is a pytest run against the `tests/` directory. The scope block states that this operation is permitted to receive `tests/` and nothing else.

Generate a signing key pair:

    $ aesn keygen --out ~/.config/aesn/signing.key
    wrote ~/.config/aesn/signing.key
    wrote ~/.config/aesn/signing.pub

Run the plan:

    $ aesn run plan.json --key ~/.config/aesn/signing.key

      pytest tests/    exit 0   1.24s

      transcript: transcripts/2026-09-28T18-04-11Z.json
      signature:  0f3b9c2a...  (Ed25519)

## A plan with multiple operations

    {
      "operations": [
        {"type": "pytest", "args": "tests/unit"},
        {"type": "pytest", "args": "tests/e2e"},
        {"type": "psql",   "args": "SELECT count(*) FROM users"},
        {"type": "curl",   "args": "https://api.example.com/health"}
      ],
      "order": [["tests/unit", "tests/e2e"]],
      "scope": {
        "pytest": ["tests/unit", "tests/e2e"],
        "psql":   ["SELECT"],
        "curl":   ["https://api.example.com"]
      }
    }

The `order` block states that `tests/e2e` must wait for `tests/unit` to complete. The other two operations have no ordering constraint. The scope block permits pytest to test two paths, psql to issue only SELECT statements, and curl to reach only `api.example.com`.

Running this plan produces:

    $ aesn run plan.json --key ~/.config/aesn/signing.key

      pytest tests/unit                      exit 0    1.18s
      pytest tests/e2e                       exit 0    12.44s
      psql SELECT count(*) FROM users        rows 1    0.06s
      curl https://api.example.com/health    200       0.11s

## Rejection behaviour

If a plan attempts an operation outside its scope, the runner rejects the operation and stops the plan. No subprocess is spawned. No connection is opened.

Example plan:

    {
      "operations": [
        {"type": "psql", "args": "UPDATE users SET verified = true"}
      ],
      "order": [],
      "scope": {"psql": ["SELECT"]}
    }

Running this plan produces:

    $ aesn run plan.json --key ~/.config/aesn/signing.key

      psql "UPDATE users SET verified = true"
            not in scope: leading token is UPDATE, scope permits SELECT

      plan aborted. no operations executed.

The refusal occurs in the dispatcher, before the operation adapter is invoked. The database connection is never opened.

## The transcript format

    {
      "plan_hash": "e9a1c7b3...",
      "entries": [
        {
          "operation": "pytest",
          "args": "tests/unit",
          "exit_code": 0,
          "stdout_hash": "2f8e9a...",
          "stderr_hash": "a1b2c3...",
          "duration_ns": 1184723912
        }
      ],
      "signature": "MC4CAQAwBQYDK2VwBCIEIG..."
    }

Each entry records the operation that ran, the argument passed, the process exit code, a SHA-256 hash of the process output, and the elapsed time in nanoseconds. The signature covers the plan hash and the entries.

To verify a transcript on a different machine, given only the public key:

    $ aesn verify transcripts/2026-09-28T18-06-52Z.json \
          --pub ~/.config/aesn/signing.pub
    signature verifies
    plan_hash matches entries

A transcript that has been modified, or one that was signed with a different private key, fails this check.

## Known limitations

Each item below is a design boundary, not a defect that will be corrected within the current major version.

- The `psql` adapter checks only the first word of each SQL statement. A statement that does not begin with a prohibited keyword can still modify data through other means.
- AESN does not restrict what a spawned subprocess can do at the operating system level. rlimits, namespaces, and seccomp filters are not used.
- A plan carries no time limit or memory limit per operation. A single operation can consume arbitrary resources.
- The transcript is signed by the runner. The plan is not signed, unless the plan author signs it separately.
- Only three operation types are implemented. Adding a fourth requires re-establishing the scope semantics for that operation type from first principles.

## Relationship to The Mark Intelligence Group's stack

AESN is one of eight independent programs in The Mark Intelligence Group's stack. No program in the stack imports another, and no program communicates with another at runtime. The relationship is conceptual: each program occupies a distinct layer, and the outputs of each can be verified independently by outside parties.

The other programs are `tstate` (reachability analysis), `state-substrate` (cryptographic attestation of a state), `mlx-omni` (distributed-system primitives), `twin-fabric` (digital-twin consistency gate), `unified-security-ops` (security dispatch), `proof-fabric` (verification on read), and `tmig` (a verifier that produces one signed manifest over the whole stack).

Formal specification: [docs/SPEC.md](docs/SPEC.md). Relationship model: [docs/STACK.md](docs/STACK.md). Extended overview: [docs/OVERVIEW.md](docs/OVERVIEW.md).

## License

See [LICENSE](LICENSE).
