Skip to content

Review security boundaries

Apply this checklist to the assigned authentication, permissions, secrets or access review. Read the task first; the coordinator runs the work and its Astra review with scripts/heyaira-run.sh.

1. Bound the inspection

  1. Record repository, reviewed SHA, task/version and the exact paths in scope.
  2. Read the diff and follow changed authentication/authorization paths into their callers.
  3. Use source references, not private credential files, to identify credential classes.
  4. Do not print secret values, fragments, DSNs, headers, memory bodies or enrollment codes.
  5. Use synthetic identities/tokens in demonstrations and regression checks.
  6. Mark production custody and deployed grants unverified unless an authorized receipt establishes them.

Run a source-only search; inspect matching definitions, not the live environment.

rg -n 'authorize|permission|scope|membership|write_context|allowed_models|allowed_accounts|allowed_repositories' src docs/BRIDGE_PROTOCOL.md docs/concepts
git diff <base-sha> <candidate-sha> --name-only

2. Build the access-path list

  1. List entry points: MCP, HTTP, OAuth, Bridge enrollment/binding, filesystem and provider session.
  2. Trace each caller principal through authentication, project binding and operation authorization.
  3. Name the protected object and the check before the first read/write of it.
  4. Include success, denial, stale/revoked credential and cross-project cases.
  5. Check background/renewal/recovery paths as well as the main request handler.

Use one row per path; name symbols and source locations, never token values.

Entry Principal Target/project Gate before effect Granted authority Denial check Source
<route/tool> <credential class> <object> <function> <scope> <test> <file:line>

3. Compare authority with the minimum needed

  1. Compare each consumer's operation with its actual scopes, memberships and database grants.
  2. Flag a broader grant with the reachable operation it enables; propose the smallest replacement.
  3. Confirm project/resource/instance checks and current membership narrowing at write boundaries.
  4. Check that worker credentials permit assigned reads/RESULT only; verifier credentials stay read-only.
  5. Trace expiry, cancellation and revocation checks before accepting a lease-bound action.
  6. Confirm provider sessions cannot inherit unrelated MCP servers or GitHub publishing credentials.
  7. Inspect filesystem and network allowlists for actual enforcement; do not accept prompt text as a gate.
  8. Check model, provider-account slot and repository allowlists against the selected task assignment.
  9. Compare server account-slot authorization with Mac policy allowed_accounts; require both.
  10. Mark local Bridge policy uninspected if that repository/configuration is unavailable.

4. Record custody and rotation without values

  1. Inventory credential names/classes, consumers, storage boundary, holder role and revocation path.
  2. Record last verified rotation date, approved interval and next due date; use unknown if absent.
  3. Separate protocol expiry from a proposed operator rotation schedule.
  4. For a proposed rotation, list all consumers, replacement order, validation and recovery owner.
  5. Obtain the required owner's consent before rotating/revoking secrets or changing access grants.
  6. Leave production changes to DevOps under the project's recorded authorization.
  7. Keep enrollment codes on the approved direct delivery path to the owner; never request their value.

Use this value-free inventory shape.

class=<name>; consumers=<roles/services>; storage=<boundary, not contents>
holder=<role|unverified>; last_rotation=<date|unknown>; interval=<approved|proposed>
next_due=<date|unknown>; revoke=<procedure reference>; approval=<decision ID|missing>

5. Reproduce and grade findings

  1. Give each finding an ID, input/principal, reachable effect, file:line and reproducible check.
  2. Grade P1 for data loss, security breach or outage; P2 for reachable incorrect behavior.
  3. Grade P3 for lower-impact improvements; distinguish a proposal from a confirmed vulnerability.
  4. State confidence and missing live evidence; do not infer compromise from an unknown rotation date.
  5. Return P1/P2 as blocking findings for the reviewed boundary; route P3 to follow-up.
  6. Give the coordinator repair requests with finding IDs, target paths and acceptance checks.
  7. Identify owner decisions explicitly: reserved consent, sign-in, grants, secret rotation or production go.
  8. Send one review summary to the owner only through the authorized reporting path.
  9. Return findings and evidence through the assigned execution contract; do not fix or grant access in a review.

Sources