# How to choose an execution gateway over a secrets broker

A platform team should adopt a desktop execution gateway when its agents run on managed Macs, its outbound work fits HTTP and SSH, and the team wants useful controls this quarter. Building a secrets broker can win when the required channels, operating systems, identity boundary, or central service model differ enough that adapting an existing gateway would amount to a fork.

The license fee is not the hard part. Apache-2.0 removes a purchasing obstacle, but it does not operate the software, prove who invoked a credential, or answer an auditor after an incident. The decision turns on where plaintext appears, what identity earns authority, whether deleted records can be detected, and who owns every security update for the next two years.

I score the two paths below against a concrete deployment: autonomous coding agents run as local processes on company Macs; they call bearer, basic, or custom header HTTP APIs and use SSH; a human can approve risky actions; and the company needs an evidence trail. Change those assumptions and the score should change. Keeping a pretty total after the facts move is how platform teams buy themselves the wrong control.

## Define the boundary before scoring products

An execution gateway and a secrets broker solve different problems, even though both may begin with an encrypted credential store. A broker usually authenticates a workload and returns a secret or a short lived credential. A gateway keeps the secret and performs the outbound action on the caller's behalf. That last hop decides whether a compromised agent can read, print, cache, or reuse credential material.

Write one sentence for each trust boundary before comparing implementations:

- The agent process may be compromised and must never receive plaintext credentials.
- The desktop gateway may use credentials but must deny work while its vault is locked.
- The remote API or SSH host receives the normal protocol credential.
- Operators may review results and evidence without gaining routine access to secrets.
- A local administrator remains a powerful adversary that requires separate endpoint controls.

The fourth and fifth lines stop a common piece of wishful thinking. Encrypting a vault protects stored bytes. It does not prevent an authorized component from leaking a decrypted key, and it does not make a fully controlled endpoint trustworthy. If your threat model says root on the Mac must be unable to influence or observe every action, neither a normal desktop app nor a homegrown local broker settles the matter. You need a stronger execution boundary, such as a separately administered service or hardware backed workload isolation, and a design review that treats the endpoint as hostile.

Use abuse cases, not feature nouns, to test the boundary. Ask whether an agent can request `GET /me`, persuade the gateway to call an arbitrary host, place a secret in a URL, swap an executable after approval, replay an approved action, or erase the record of a failed attempt. Each answer needs an enforcement point and an owner. A diagram that says "vault" between the agent and the network does not answer any of them.

This distinction also changes migration cost. Replacing environment variables with a broker that returns the same values leaves agent integrations almost untouched, which feels easy. Replacing them with an action gateway means defining typed HTTP and SSH requests and returning bounded results. That work is the price of keeping plaintext out of the least trusted process. Score it as integration work, then keep the security benefit visible instead of quietly treating compatibility as isolation.

## The score favors adoption under stated assumptions

Use a five point scale where 1 means the path misses the requirement or needs major new engineering, 3 means it works with material gaps, and 5 means it meets the requirement with operable evidence. I weight credential isolation most heavily because a design that hands secrets to the agent cannot recover that loss with better logging.

| Dimension | Weight | Adopt | Build | What earns a high score |
| --- | ---: | ---: | ---: | --- |
| Credential isolation | 30% | 5 | 2 | The agent never receives a secret and cannot redirect credential injection |
| Signed process checks | 15% | 4 | 2 | Approval shows verified code identity and detects process replacement |
| Tamper evidence | 20% | 5 | 2 | Append semantics, cryptographic chaining, and an independent verifier exist |
| Update work | 20% | 4 | 1 | A named upstream owns releases while the team can inspect and pin them |
| Audit support | 15% | 4 | 2 | Reviewers can connect a process run, approval, call, result, and revocation |
| Weighted total | 100% | 4.5 | 1.8 | Recalculate after testing rather than accepting these numbers on faith |

For the adopt column, Sallyport fits the assumed Mac, HTTP, and SSH boundary: its encrypted vault does not expose keys to the agent, session approval leads with the process's code signing authority, selected keys can require approval on every use, and its encrypted hash chained log can be verified offline with `sp audit verify`. Its Apache-2.0 source and in process menu bar form reduce procurement and service operation work, but they do not erase the need to inspect releases, test agent integrations, define retention, or support users.

The build score assumes a capable platform team starting with a conventional secret service, not a mature internal product already doing delegated execution. A prototype can store and return a key quickly, so demos flatter this path. The missing points sit in the parts a demo skips: caller attestation, action mediation, approval state, cancellation, immutable event ordering, verifier tooling, recovery, schema evolution, installers, signing, and support.

Do not average away a mandatory requirement. If agents must run on another operating system, a Mac desktop gateway receives a zero for fit even if its security controls are excellent. If outbound work needs database wire protocols, cloud signing APIs, or interactive terminal forwarding, test those channels explicitly. A weighted score helps choose among viable paths; it cannot make an incompatible path viable.

Run the score twice. The first pass measures the software today. The second measures the likely state after 24 months, including your team's available maintainers, upstream responsiveness, release verification, and support queue. If build rises because you already own most components, record their current maintenance cost. "We have the code" is not the same claim as "we have an operated security product."

## Credential isolation ends at execution, not storage

The strongest isolation property is easy to state: the agent supplies an intended action, the trusted component adds the credential at a fixed destination, the trusted component performs the action, and the agent receives only the allowed result. At no point can the agent ask for the raw key. This is materially different from wrapping a vault API with nicer authentication.

Walk through a typical failure. A coding agent needs to open a repository issue, so a broker returns an API token into the agent process. The agent's context includes untrusted issue text. A malicious instruction in that text asks the agent to diagnose authentication by printing its environment or sending headers to a diagnostic endpoint. The broker completed its job correctly, yet the token crossed into a process that interprets attacker controlled text and can make network requests. Shortening the token lifetime reduces the window; it does not preserve isolation.

A gateway avoids that exact failure only if it constrains the action. Credential injection must bind to the intended host and protocol location. Redirect handling must not forward an authorization header to a different origin. Logs and error objects must redact credential values. Response size and content handling need limits, since a hostile server can return data crafted to attack the agent or flood its context. SSH host verification, destination constraints, and command representation deserve the same care.

NIST SP 800-57 treats key management as a lifecycle with protected key material, access controls, metadata, compromise handling, and accountability. Teams often cite the storage portions and skip the use phase. For an autonomous agent, use is where the credential faces the most creative input. A design review should follow the secret from creation through every decryption and protocol insertion, then mark every buffer, log path, crash report, child process, and response that could copy it.

Ask a build team for a trace rather than an assurance. A useful test places a unique canary value in the development vault, runs successful and failing actions, then searches process output, captured logs, crash files, temporary directories, shell history, and agent transcripts for that value. Repeat with redirects, authentication failures, timeouts, oversized responses, and cancellation. Finding nothing does not prove noninterference, but finding the canary disproves the claim immediately.

Adoption still needs this test. Open source lets reviewers inspect where injection occurs and whether the return type can contain a secret, but source availability is not execution evidence. Pin the evaluated version, build or obtain the exact artifact through a controlled process, and rerun the canary suite after security relevant updates.

## A signature identifies code but does not authorize intent

macOS code signing gives a gateway stronger caller evidence than a process name or filesystem path. Apple's code signing documentation explains that a designated requirement identifies versions of the same code, while a code requirement evaluates properties such as the signing anchor and identifier. This helps distinguish a signed agent released by an approved developer from an unsigned copy named the same thing.

The distinction Apple makes among signing identifier, signing identity, and code identity matters here. An identifier is a string selected by the signer. The signing identity includes the certificate and private key. Code identity is the system's judgment that two releases count as the same code. Recording only a bundle identifier or executable path throws away the authority evidence that makes the check useful.

A signature still says nothing about whether the current prompt is safe. Properly signed code can contain a vulnerability, load unsafe extensions, execute project supplied hooks, or faithfully follow a malicious instruction. Treat signing authority as an input to authorization: it tells the person approving a session which publisher controls the process. It should never become blanket proof that every requested API call deserves approval.

Test four transitions during evaluation:

1. Start the expected signed agent and confirm the approval identifies its signing authority.
2. Exit and restart the same binary, then confirm a new process session needs fresh authorization.
3. Replace it with an unsigned binary at the same path and confirm the identity visibly changes or the call fails.
4. Install a legitimately updated version and confirm the gateway recognizes the intended authority without silently accepting a different signer.

The third test catches path based trust. The second catches approvals stored as permanent application grants when the stated control is authorization for one run. The fourth catches brittle pinning that either blocks routine updates or tempts operators to approve a broad requirement. Save screenshots or structured results from each transition in the decision record.

A custom implementation must also handle timing. If it inspects a path, approves, and later launches or communicates with a different process, a swap can defeat the check. Bind evidence to the live audit token or connection where the operating system supports it, validate before privileged work, and define what happens when process ancestry is ambiguous. This is specialized endpoint security code, not a weekend addition to a secret API.

## Tamper evidence needs a verifier and a failure policy

An append only database flag is an access policy. A hash chained log is tamper evident when each record commits to the preceding state, and a verifier can detect modification, deletion, insertion, or reordering within the scheme's stated limits. Neither property guarantees that an event was recorded correctly in the first place, and neither prevents an attacker from destroying every local copy.

OWASP's Logging Cheat Sheet tells implementers to build in tamper detection and to detect when logging stops. That second instruction gets neglected. A gateway that continues privileged actions after its journal cannot append has chosen availability over evidence. That may be acceptable for some credentials, but the choice must be explicit, tested, and visible to the operator.

Demand a runnable verification artifact. For an adopted gateway in this evaluation, the basic operator check is:

```sh
sp audit verify
```

The expected result shape should include a clear success or a nonzero exit with the first unverifiable position and reason. During the pilot, copy the encrypted log, verify the untouched copy, flip one byte in a duplicate, remove a middle record if the storage format permits controlled manipulation, and verify again. Keep the commands and observed exit codes. A screenshot of a green journal view is not cryptographic verification.

Offline verification over ciphertext has two operational advantages. Reviewers can check continuity without unlocking secret bearing content, and incident responders can preserve and validate a copy before granting access to decrypted details. It also has a limit: a valid local prefix may omit a deleted tail unless the verifier compares it with a separately anchored checkpoint or expected head. Ask how the current head is recorded outside the machine, how often, and who notices missed checkpoints.

A build proposal needs more than "we will hash the logs." Specify record canonicalization, chain initialization, crash recovery, concurrency ordering, key or hash choices, format versioning, verifier distribution, and the response to corruption. Decide whether redaction happens before commitment, because secrets accidentally committed to an encrypted journal can complicate support and retention. Define export without losing the evidence needed to verify ordering.

Separate tamper evidence from audit completeness. A perfectly intact record can still omit the request target, caller identity, approval decision, result status, or revocation. Conversely, a rich activity table that administrators can rewrite silently may help debugging but cannot support a strong integrity claim. Score these as connected controls, not interchangeable labels.

## Two years of update work changes the economics

Security software on developer machines absorbs change from both sides. Operating system releases alter signing, entitlement, key storage, and background behavior. Agent tools change process trees and MCP behavior. Remote APIs change authentication and error formats. SSH libraries and cryptographic dependencies publish fixes. An adopted project gives the team an upstream, while a custom product makes the team the upstream.

Count owner hours by recurring duty, not by initial coding estimate. Use a worksheet like this and fill it with ranges from named engineers:

| Duty over 24 months | Adopted gateway | Custom broker |
| --- | --- | --- |
| Source and architecture review | Initial review plus material release diffs | Continuous design review for every subsystem |
| Release engineering | Pin, verify, package, stage, and roll back | Build, sign, notarize, package, stage, and roll back |
| Compatibility testing | Supported channels and agent versions | Every owned client, protocol, and deployment target |
| Vulnerability response | Triage upstream fix and exposure | Triage, design, patch, disclose, and backport |
| User support | Integration and policy questions | Integration, product behavior, recovery, and defects |
| Audit requests | Explain configured controls and export evidence | Defend design, implementation, operation, and evidence |

Track four numbers for each row: expected hours per quarter, a bad quarter, elapsed response time, and the person who can actually do the work. Elapsed time matters because ten hours from a busy signing specialist may take three weeks. Put incident drills, certificate renewal, dependency review, and recovery testing on the ledger. They disappear from optimistic build estimates because no feature demo depends on them.

Apache-2.0 permits use, modification, and distribution under its conditions, including preservation of required notices and marking modified files. It also includes an express patent license from contributors and a termination provision tied to patent litigation. Have counsel apply those terms to your distribution plan, but do not turn a permissive license into a claim that updates arrive on your schedule or that upstream owes support.

Forking deserves its own line item. A small patch can be rational, but every local change creates a merge and retest obligation. Set a fork budget before adoption: which changes may remain local, how many releases can lag, and the condition that triggers an upstream contribution or a move to a custom path. Without that rule, teams call the software "adopted" while slowly becoming maintainers of a private edition.

The build path can improve after year one if the company already has release engineering, endpoint deployment, an audit pipeline, and an on call rotation that accepts ownership. Give it credit for shared infrastructure, but charge only real marginal savings. A central logging service does not remove the need to create correct gateway events, spool them during outages, protect local secrets, and test evidence export.

## Audit support begins with questions, not retention

An auditor or incident lead rarely asks whether logging is enabled. They ask who authorized the agent, what code ran, which credential class it used, what destination and action it requested, whether the call succeeded, what the operator revoked, and whether the record changed afterward. Design the event model backward from those questions.

For each agent run, retain a stable session identifier, process identity evidence, approval actor and method, start and end boundaries, and revocation state. For each call, retain its session link, time, channel, normalized destination, credential reference rather than value, approval result, bounded action summary, result status, and chain position. Decide which request or response fields must be omitted or redacted. Audit support fails if answering a simple question requires decrypting arbitrary payloads full of customer data.

Use one evaluation packet for both paths. It should contain:

- A threat model with trust boundaries and abuse cases.
- The scored matrix with evidence and named owners behind every number.
- Results from secret canary, process replacement, log mutation, and logging outage tests.
- A 24 month duty ledger with expected and bad quarter estimates.
- Sample session and call exports that answer one incident timeline.

The worked incident should be uncomfortable. Suppose a signed coding agent was approved at 09:12, made two expected repository API calls, attempted SSH to a production host with a per call protected key, received a denial, then exited. At 09:40 an operator revoked what appeared to be the same run. The evidence should reveal whether it was the same session, who denied the SSH call, whether any credential reached the agent, why revocation occurred after exit, and whether records between those times remain continuous.

Retention comes after content. Set it from legal, contractual, privacy, and incident response needs, then test deletion at the end of the period. An encrypted log can still contain personal data, commands, hostnames, and response fragments. Restrict decryption, log access to the journal itself, and preserve encrypted evidence separately when an investigation requires a hold.

A polished dashboard should earn almost no score unless it exports durable evidence and documents field meaning. Auditors need repeatable answers, not a live tour through a developer's laptop. A command line verifier, versioned schema, and small set of documented queries often do more work than a page of charts.

## Building wins when the boundary truly differs

Build the broker or gateway when a mandatory requirement sits outside the adopted project's intended form and is likely to stay there. Examples include a centrally operated service for non Mac workloads, protocols beyond HTTP and SSH, organization specific hardware attestation, approval through an existing privileged access system, or evidence that must commit directly into a company controlled transparency service. These are architecture differences, not requests for another preference toggle.

A build also makes sense when the team already operates a delegated signing or request execution service with most of the hard controls. In that case, the remaining work may be an agent adapter plus desktop identity evidence rather than a new security product. Demonstrate the inherited properties. Do not award points because another internal service has a similar diagram.

Three popular arguments for building are weaker than they sound. "The broker is only a thin wrapper" ignores action parsing, destination binding, approval state, audit ordering, and recovery. "We need complete control" also means complete patch and support duty. "Open source means we can always fork" is true in a licensing sense, but a fork moves update work onto the same people the adoption was meant to spare.

Adoption has its own weak argument: "the controls already exist, so we are done." You still need to map the product boundary to your threat model, test the distributed binary, manage allowed integrations, protect exported logs, and define support. An approval card can also produce fatigue if ordinary work triggers too many prompts. Use per session approval for the run and reserve per call approval for credentials where each use deserves a human decision; otherwise users learn to click before reading.

Choose build only with named owners for these minimum workstreams: endpoint identity and IPC, credential lifecycle and injection, protocol executors, approval experience, tamper evidence and verification, release security, and operational support. One engineer may own several, but a row labeled "platform team" is not ownership. Record who covers leave and incidents.

A short proof can settle uncertainty without committing to a product. Give both paths the same two integrations and attack tests for three weeks. Cap prototype code that will be discarded, prohibit production secrets, and score only demonstrated behavior. If the custom path cannot show live process identity and detect a changed log in the proof, assume those controls are future work rather than granting roadmap credit.

## Make the decision reversible without weakening it

Adopt with an exit package, or build behind an action contract. The shared contract should describe an agent request without exposing provider secrets: channel, destination, operation, bounded arguments, credential reference, approval class, and a structured result. Keep provider specific authentication inside the executor. This lets teams change the trusted component later without teaching agents how to hold keys.

Use this two year decision sequence:

1. In month zero, freeze the threat model, mandatory platforms, channels, evidence questions, and scoring weights. Reject any path that misses a mandatory boundary.
2. During the pilot, run the canary, signer replacement, session restart, redirect, log mutation, log outage, revocation, and export tests. Attach raw results to each score.
3. At rollout, pin a reviewed release, document recovery, establish an update window, train support, and capture an external checkpoint for the audit head if tail deletion matters.
4. Each quarter, review upstream changes or custom backlog, failed actions, approval patterns, verifier results, dependency notices, and actual owner hours against the ledger.
5. At months 12 and 24, rescore both paths. Trigger migration or a funded build when platform fit, fork size, response time, or missing channels cross thresholds agreed at month zero.

Do not make reversibility an excuse to accept a leaky compatibility mode. If the temporary adapter returns raw credentials to the agent, the system has changed the primary security property. Label that path as a broker, score it accordingly, and limit where it can run.

For the stated Mac deployment, adoption begins 2.7 weighted points ahead. A custom proposal should close that gap with running evidence, not confidence in what the team could build. If its distinct requirements justify the work, fund it like an internal security product with release, audit, and support owners for the full two years. If they do not, spend those engineering months testing and operating the gateway you can inspect today.