The Full Reference Architecture

The Full Reference Architecture¶

This is the strongest version of the model: the target state when every supporting system is available. That means enterprise identity, source control, build, signing, provenance, policy, secrets or privileged access management, isolated execution, a source of truth, validation, telemetry, and evidence.

Starting there is deliberate. Defining the destination first is what lets you make the reductions honestly. A team that starts from what it already has tends to draw an architecture around it, and then cannot tell which of its gaps are acceptable and which one is the next incident. The adoption profiles are those reductions, made on purpose.

The Target State¶

graph TD
    RQ[Author · Approver · CI · Scheduler · Agent] --> ID[Requester identity<br/>MFA or attestation]
    ID --> GW[Execution gateway<br/>policy enforcement point]
    GW --> WI[Workload identity<br/>+ attestation]
    GW --> AT[Artefact trust<br/>+ provenance]
    GW --> CX[Context and risk<br/>+ target scope]
    WI --> PD[Policy decision service<br/>default DENY · explicit ALLOW]
    AT --> PD
    CX --> PD
    PD -->|approved request| PB[Just-in-time privilege broker<br/>workload credential issuer]
    PB -->|short-lived authority| RN[Ephemeral, isolated runner]
    RN --> SOT[Source of truth]
    RN --> TG[Target systems]
    SOT --> VA[Independent validation]
    TG --> VA
    VA --> EV[Telemetry + protected evidence]
    EV --> SI[SIEM · review · response]

    style GW fill:#c8e6c9
    style PD fill:#c8e6c9
    style PB fill:#ffe0e0
    style RN fill:#fff4e6
    style VA fill:#e1f5ff
    style EV fill:#eeeeee

Look at where the privilege broker sits: below the policy decision. In most estates it is effectively at the top, because the credential exists before anyone has asked for anything.

Two structural rules fall out of the diagram:

• There is one way in. If a caller can reach the same credential or the same target by another route, the gateway is advisory. Bypass paths are found and closed, not documented.
• The decision is not made by the thing being decided about. The workload supplies evidence. It never evaluates it.

The publication path¶

Runtime verification is only as meaningful as the evidence it verifies. The gateway can check a signature and a provenance record at execution time, but only if something trustworthy produced them earlier.

graph LR
    A[Reviewed source] --> B[Controlled repository]
    B --> C[Controlled build<br/>tests · security checks]
    C --> D[Signed artefact<br/>+ provenance]
    D --> E[Approved artefact store]
    E --> F[Execution references<br/>an immutable artefact]

    style D fill:#c8e6c9
    style F fill:#fff4e6

SLSA defines provenance as verifiable information about where, when, and how an artefact was produced. Its verification guidance checks that information against trusted builder identities and expected build parameters, rather than accepting the presence of metadata as proof. That distinction matters here. A provenance record nobody verifies is decoration.

Component by Component¶

Twenty-four components, grouped under the nine sentences from the overview, plus a tenth group for keeping trust withdrawable once it has been given.

1. Prove who is asking¶

Two identities, not one. The Governed Automation Reference Architecture already insists that users and workloads authenticate separately, and this is why. A shared service account collapses both into a single principal, and policy can no longer tell who asked from what ran.

2. Prove what will run¶

This is the remediation pack argument applied to code rather than to a change. A checksum over a pack proves the change is the one that was approved. A digest and a signature over the workload prove the code applying it is the one that was reviewed. Most estates have neither, and the ones that have the first rarely have the second.

3. Establish where it came from¶

In most network automation the top-level script is a few hundred lines and the dependency tree is tens of thousands. Signing the script and ignoring the tree verifies the part least likely to be the problem. The Python Engineering Standard sets the dependency bar this component verifies.

4. Decide what it may do¶

This is where identity is not capability is enforced. A request names the capability it wants, and policy grants or refuses that capability specifically. A verified compliance workload asking to reload a device is not a trusted workload doing something slightly unusual. It is a known workload making an unauthorised request, and the gateway has to be able to tell the difference.

5. Constrain where it may do it¶

Scope is constrained twice. Logically, targets are resolved through an authoritative source before policy evaluates them: a policy that evaluates the target name a caller typed has approved a string, and whatever the runner later resolves that string to was never decided on. Physically, the workload can reach only what it was approved to touch, so a mistake in policy does not become access to the whole estate.

This sentence and the one before it are separate questions, not separate moments. In the execution lifecycle, targets are resolved at stage 5 and evaluated together with everything else at stage 6.

6. Grant only the authority required¶

Note the dependency on groups 4 and 5. Retrieving secrets at runtime, the runtime retrieval pattern, is necessary but not sufficient. What this architecture adds is when: the secret cannot be retrieved until the gateway has said yes, and dynamic secrets are one way to make sure it expires shortly afterwards.

7. Execute within defined boundaries¶

This is the group where security and operational safety stop being separate subjects. A circuit breaker is an operational control, and it is also what stops a defective or compromised workload from reaching its fiftieth device. The production-grade principles cover each of these in depth. The architecture's contribution is to make them conditions of execution rather than good habits.

8. Validate the resulting state independently¶

Independence is the part that is easy to drop. A deployment script that runs its own checks at the end is better than one that runs none, but it shares every assumption, every parser, and every bug with the code it is checking. The capstone pipeline keeps the two apart for exactly this reason. Proving the Change with PyATS is built around a deploy that succeeded and an uplink that is down.

9. Prove what happened¶

Alert on denials. A gateway that refuses quietly is half a control: the refusal protected this run, but the attempt is information, and a pattern of attempts is an investigation. Tool Contracts and Failure Modes makes the same argument for agents.

10. Keep trust withdrawable¶

Break-glass is the component most likely to be skipped and the one most likely to be needed. If you do not design it, it still exists: as a shared admin password in a spreadsheet, discovered during the review after the outage.

It is also not an exception. An exception is a planned, time-bound deviation from a control. Break-glass is an unplanned emergency route through one. They need different approvals and leave different evidence.

The Policy Decision¶

The decision is an evaluation of evidence, context, and requested capability, not a single trusted-or-untrusted flag.

decision = f(
    requester_identity,
    workload_identity,
    artefact_digest,
    publisher_and_provenance,
    requested_capability,
    target_identity_and_classification,
    environment,
    approval_context,
    current_risk_and_posture,
    policy_version,
)

if mandatory evidence is missing or policy is not satisfied:
    DENY
else:
    ALLOW with constrained capability, scope, and lifetime

ALLOW is never unqualified. An allow carries its constraints with it — which capability, against which targets, for how long — and the privilege broker issues exactly that and no more.

The architecture does not prescribe a policy engine. A dedicated decision service, an existing platform's authorisation controls, or a version-controlled policy file evaluated by a trusted runner can each fill the role. What it requires is that the decision is:

• external to the workload it governs
• reproducible enough to explain afterwards: the same inputs and the same policy version give the same answer
• enforceable at the execution boundary, not merely recorded there

policy_version is an input for the second reason. An auditor asking why a run was allowed in March needs the policy as it stood in March.

The Execution Lifecycle¶

Fourteen stages. The workload holds privilege only between stages 7 and 12.

For a change, the remediation pack travels with the request at stage 1, and its revalidation happens at stage 9.

Map your current automation onto this table and the usual result is that stages 7, 10, and part of 13 exist, and everything else is implicit. That is not a failing grade. It is the starting position the adoption profiles are written for.

Risk Classes and What the Gateway Demands¶

The architecture uses the site's existing automation risk classes unchanged. Every class goes through the gateway, including read-only work, because a read is still privileged access: show running-config is a read that can expose every credential on a device. What the class changes is how much the gateway demands before it says yes.

R3 covers a wide range of change, and the form of approval should scale within it:

• Small, deterministic, reversible change — a port description, an access VLAN on one port. Approval can be granted once, as a standard change bound to a specific artefact version and a bounded scope, with an expiry. Every run still passes pre-flight and post-change validation.
• Broad or material change — many devices, or one important one. A per-execution approval, staged rollout, and an explicit rollback path.
• Upgrades, reloads, and changes to security controls — an approver independent of the requester, binding to a change window, canary stages, and just-in-time privilege. Where scale makes this R4, classify it as R4.

In every case the approval is a record with a named approver and an expiry, as NP-CHG-03 requires. A standard change is an approval given in advance, not an approval skipped.

Break-glass is not a class. Emergency, destructive, or unusually sensitive authority outside these paths goes through the break-glass route described in group 10, and every use of it is reviewed afterwards.

The Evidence Record¶

A run should be reconstructable as a chain of decisions and outcomes. The schema is yours to choose; the categories are not. Without recording any secret, capture:

• a unique execution and correlation ID
• requester identity, with its authentication and approval context
• workload identity, version, digest, and the result of publisher and provenance verification
• policy version, decision, reason, and the context it evaluated
• the capability requested and the capability authorised, recorded separately
• resolved target identities with their environment and risk classification
• a reference to the privilege issued — an issuance identifier, never the secret itself
• runner identity and posture, where available
• the pre-flight result
• execution stages and their bounded results
• the independent validation result
• revocation, rollback, and exception events
• start and end timestamps, and the final disposition

This extends the per-run evidence model in Building Audit-Ready Automation with the trust decision itself. That page records what the run did. This adds why it was allowed to.

AI-Triggered Automation¶

The model matters most when an AI system can request operational actions. The agent becomes another requester, not a privileged exception.

graph TD
    AG[AI agent] -->|requests an approved capability| GW[Execution gateway]
    GW --> C1[Verify agent<br/>and request context]
    GW --> C2[Verify approved<br/>workload and artefact]
    GW --> C3[Evaluate operation,<br/>target, and risk]
    GW --> C4[Require human approval<br/>where policy says so]
    C1 --> EX[Scoped workload execution]
    C2 --> EX
    C3 --> EX
    C4 --> EX
    EX --> VE[Independent validation<br/>+ evidence]

    style AG fill:#f3e5f5
    style GW fill:#c8e6c9
    style EX fill:#fff4e6
    style VE fill:#e1f5ff

The agent never receives a generic execution capability that sidesteps the gateway. That case is argued in full in Why Your Agent Must Not Have an execute_command Tool.

What Trusted Automation Execution adds is that the governed tools an agent calls are themselves workloads. Each call is identified, verified, checked against policy, and given scoped authority, exactly as it would be for an engineer or a pipeline. Both the agent's AI risk class and the workflow's R class apply.

Mapping to the Control Catalogue¶

Most of this architecture is already required, piece by piece, by the Automation Control Catalogue. What it adds is the ordering — evidence before privilege — and a handful of requirements the catalogue does not yet state.

The right-hand column is what an assessment against the catalogue alone would not catch.

Ten Things That Must Be True¶

The architecture is working when all of these hold.

1. An altered workload cannot exercise privileged authority.
2. An approved workload cannot exceed its declared and authorised capability.
3. An approved workload cannot silently expand to unauthorised targets.
4. A caller cannot bypass the enforcement path to obtain the same authority.
5. In the target state, privilege does not exist before the trust decision.
6. High-risk actions can require independent approval.
7. Operational success is determined by independent validation, not by process exit status.
8. Every privileged run can be correlated to its requester, workload, decision, scope, result, and evidence.
9. Trust can be revoked quickly — for a workload, a publisher, a policy grant, or a credential path.
10. The architecture can be implemented at lower maturity without redefining its trust principles.

The first nine double as acceptance tests for any implementation, at any profile. The tenth is a test of the architecture itself, and the adoption profiles are the evidence offered for it.

Continue¶

• Previous: Trusted Automation Execution
• Next: Threat and Failure Model
• Related: Governed Automation Reference Architecture · Remediation Packs