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.

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. Relationship model: docs/STACK.md. Extended overview: docs/OVERVIEW.md.

License

See LICENSE.