morluto/rea
1
0
Fork 0
mirror of https://github.com/morluto/rea.git synced 2026-11-05 06:45:22 +00:00
Code Issues 1.3k Projects Packages Wiki Activity

[GH-ISSUE #114] Introduce unified scoped permission grants for local REA capabilities #73

New issue
Closed
opened 2026-10-15 18:20:50 +00:00 by bsakaguchi · 1 comment
bsakaguchi commented 2026-10-15 18:20:50 +00:00
Owner
Copy link

Originally created by @morluto on GitHub (Jul 13, 2026).
Original GitHub issue: https://github.com/morluto/rea/issues/114

Summary

Replace capability-specific startup-environment friction with one unified, auditable policy engine for local filesystem, executable, mount, process, environment, and network permissions.

Retain administrator/startup policy as a hard ceiling. Add once, session, and optional project grants within that ceiling. #96 remains the process-capture elicitation consumer; this issue defines the shared policy substrate.

Current state in REA 1.3.0

Separate environment variables gate different capabilities, including:

  • process executable and working roots;
  • process environment names and network mode;
  • Evidence import/export roots;
  • investigation input roots;
  • investigation workspace roots;
  • analysis snapshot roots;
  • native DMG mounting.

This is safe but fragmented. Agents receive disabled/outside-root errors, users edit MCP configuration, and the server often requires restart.

Goals

  • One policy vocabulary and evaluator.
  • Least-privilege grants scoped by capability.
  • Administrator ceilings plus user/session grants.
  • Exact subset checking on every operation.
  • Clear review, audit, expiry, and revocation.
  • No secret values in consent or logs.
  • Runtime reload without restart where safe.
  • Consistent CLI and MCP behavior.

Permission model

A grant should describe:

  • capability: process_capture, evidence_read, evidence_write, investigation_input, snapshot_read, snapshot_write, artifact_extract, native_mount, or another registered capability;
  • filesystem roots and access mode;
  • executable paths/roots;
  • allowed environment variable names;
  • network mode: none, loopback, or explicitly approved host/external scope;
  • mount permission;
  • operation limits;
  • lifetime: once, session, or persistent project;
  • issuer and creation time;
  • parent administrator ceiling;
  • audit/revocation identity.

Evaluation

For every operation:

  1. Normalize requested paths without following unsafe escapes.
  2. Build the exact requested scope.
  3. Load the administrator ceiling.
  4. Load applicable session/project grants.
  5. Prove requested scope is a subset.
  6. Either execute, elicit a bounded grant where supported, or return typed remediation.
  7. Record the decision without storing secret values.

Filesystem roots suggested by a client are context, not authorization.

Lifetimes

Once

Valid for one normalized operation identity and consumed after use.

Session

Held in memory, bound to the MCP connection/auth context, and revoked on disconnect.

Project

Explicitly persisted in an owner-only policy store, bound to canonical project identity, inspectable and revocable. Never the default.

User experience

Provide:

  • rea policy status;
  • rea policy explain ;
  • rea policy list;
  • rea policy revoke ;
  • dry-run evaluation showing missing scope;
  • exact restart-required status if runtime reload is impossible.

MCP-capable clients may use form elicitation from #96. Non-elicitation clients receive exact structured configuration guidance.

Security requirements

  • Startup/admin policy is a maximum ceiling unless changed through an explicit trusted local flow.
  • Agents cannot broaden their own ceiling.
  • Symlink, canonicalization, and macOS /var versus /private/var behavior must be handled consistently.
  • Environment values are never displayed or persisted in grants.
  • Loopback and external networking are separate permissions.
  • Grants do not authorize unrelated tools merely because paths overlap.
  • Revocation affects future operations immediately.
  • Active operations follow documented revocation semantics.
  • Policy files use owner-only permissions and atomic writes.
  • Audit records exclude credentials and captured content.

Acceptance criteria

  • All gated local capabilities use one shared policy evaluator.
  • Existing environment variables map into the administrator ceiling for compatibility.
  • Once and session grants work without server restart.
  • Optional project grants are explicit, inspectable, and revocable.
  • Every denial returns requested scope, missing scope, remediation, and restart requirement through #100's typed contract.
  • #96 process-capture elicitation issues grants through this engine.
  • Loopback-only networking is enforceable independently of external networking.
  • Path canonicalization and symlink escapes fail closed.
  • Session grants disappear on disconnect.
  • Tests cover subset reuse, expansion, conflicting grants, expiry, revocation, canonical aliases, symlinks, environment names, network modes, and non-elicitation fallback.
  • CLI and MCP share identical evaluation semantics.
  • Documentation includes migration from current environment variables.

Non-goals

  • Replacing OS-level sandboxing.
  • Treating REA as a security sandbox.
  • Storing secrets in policy.
  • Automatically granting access based on workspace roots.
  • Allowing elicitation to override an administrator ceiling.

Relationships

  • #96 implements the process-capture consent workflow.
  • #101 reflects policy availability in tool discovery.
  • #100 defines permission-required structured errors.
  • #97 task execution must retain the initiating grant context.
Originally created by @morluto on GitHub (Jul 13, 2026). Original GitHub issue: https://github.com/morluto/rea/issues/114 ## Summary Replace capability-specific startup-environment friction with one unified, auditable policy engine for local filesystem, executable, mount, process, environment, and network permissions. Retain administrator/startup policy as a hard ceiling. Add once, session, and optional project grants within that ceiling. #96 remains the process-capture elicitation consumer; this issue defines the shared policy substrate. ## Current state in REA 1.3.0 Separate environment variables gate different capabilities, including: - process executable and working roots; - process environment names and network mode; - Evidence import/export roots; - investigation input roots; - investigation workspace roots; - analysis snapshot roots; - native DMG mounting. This is safe but fragmented. Agents receive disabled/outside-root errors, users edit MCP configuration, and the server often requires restart. ## Goals - One policy vocabulary and evaluator. - Least-privilege grants scoped by capability. - Administrator ceilings plus user/session grants. - Exact subset checking on every operation. - Clear review, audit, expiry, and revocation. - No secret values in consent or logs. - Runtime reload without restart where safe. - Consistent CLI and MCP behavior. ## Permission model A grant should describe: - capability: process_capture, evidence_read, evidence_write, investigation_input, snapshot_read, snapshot_write, artifact_extract, native_mount, or another registered capability; - filesystem roots and access mode; - executable paths/roots; - allowed environment variable names; - network mode: none, loopback, or explicitly approved host/external scope; - mount permission; - operation limits; - lifetime: once, session, or persistent project; - issuer and creation time; - parent administrator ceiling; - audit/revocation identity. ## Evaluation For every operation: 1. Normalize requested paths without following unsafe escapes. 2. Build the exact requested scope. 3. Load the administrator ceiling. 4. Load applicable session/project grants. 5. Prove requested scope is a subset. 6. Either execute, elicit a bounded grant where supported, or return typed remediation. 7. Record the decision without storing secret values. Filesystem roots suggested by a client are context, not authorization. ## Lifetimes ### Once Valid for one normalized operation identity and consumed after use. ### Session Held in memory, bound to the MCP connection/auth context, and revoked on disconnect. ### Project Explicitly persisted in an owner-only policy store, bound to canonical project identity, inspectable and revocable. Never the default. ## User experience Provide: - rea policy status; - rea policy explain <operation-or-scenario>; - rea policy list; - rea policy revoke <grant-id>; - dry-run evaluation showing missing scope; - exact restart-required status if runtime reload is impossible. MCP-capable clients may use form elicitation from #96. Non-elicitation clients receive exact structured configuration guidance. ## Security requirements - Startup/admin policy is a maximum ceiling unless changed through an explicit trusted local flow. - Agents cannot broaden their own ceiling. - Symlink, canonicalization, and macOS /var versus /private/var behavior must be handled consistently. - Environment values are never displayed or persisted in grants. - Loopback and external networking are separate permissions. - Grants do not authorize unrelated tools merely because paths overlap. - Revocation affects future operations immediately. - Active operations follow documented revocation semantics. - Policy files use owner-only permissions and atomic writes. - Audit records exclude credentials and captured content. ## Acceptance criteria - [ ] All gated local capabilities use one shared policy evaluator. - [ ] Existing environment variables map into the administrator ceiling for compatibility. - [ ] Once and session grants work without server restart. - [ ] Optional project grants are explicit, inspectable, and revocable. - [ ] Every denial returns requested scope, missing scope, remediation, and restart requirement through #100's typed contract. - [ ] #96 process-capture elicitation issues grants through this engine. - [ ] Loopback-only networking is enforceable independently of external networking. - [ ] Path canonicalization and symlink escapes fail closed. - [ ] Session grants disappear on disconnect. - [ ] Tests cover subset reuse, expansion, conflicting grants, expiry, revocation, canonical aliases, symlinks, environment names, network modes, and non-elicitation fallback. - [ ] CLI and MCP share identical evaluation semantics. - [ ] Documentation includes migration from current environment variables. ## Non-goals - Replacing OS-level sandboxing. - Treating REA as a security sandbox. - Storing secrets in policy. - Automatically granting access based on workspace roots. - Allowing elicitation to override an administrator ceiling. ## Relationships - #96 implements the process-capture consent workflow. - #101 reflects policy availability in tool discovery. - #100 defines permission-required structured errors. - #97 task execution must retain the initiating grant context.
bsakaguchi 2026-10-15 18:20:50 +00:00
bsakaguchi commented 2026-10-15 18:20:52 +00:00
Author
Owner
Copy link

@morluto commented on GitHub (Jul 20, 2026):

Closing as completed. The unified scoped permission-grant engine is now shipped:

  • src/application/PermissionAuthority.ts and src/application/ProjectPermissionStore.ts implement the evaluator and persisted project grants.
  • src/domain/permissionPolicy.ts models administrator ceilings and once / session / project / administrator grant lifetimes.
  • src/cliPolicyCommands.ts exposes rea policy status|list|explain|revoke.
  • Tests (tests/permissionPolicy.test.ts, tests/permissionAuthority.test.ts, tests/projectPermissionStore.test.ts, tests/processCapturePermission.test.ts) cover subset checking, path canonicalization, symlink escape, expiry, revocation, and network-mode enforcement.

Remaining process-capture elicitation work continues in #96.

<!-- gh-comment-id:5023308055 --> @morluto commented on GitHub (Jul 20, 2026): Closing as completed. The unified scoped permission-grant engine is now shipped: - `src/application/PermissionAuthority.ts` and `src/application/ProjectPermissionStore.ts` implement the evaluator and persisted project grants. - `src/domain/permissionPolicy.ts` models administrator ceilings and `once` / `session` / `project` / `administrator` grant lifetimes. - `src/cliPolicyCommands.ts` exposes `rea policy status|list|explain|revoke`. - Tests (`tests/permissionPolicy.test.ts`, `tests/permissionAuthority.test.ts`, `tests/projectPermissionStore.test.ts`, `tests/processCapturePermission.test.ts`) cover subset checking, path canonicalization, symlink escape, expiry, revocation, and network-mode enforcement. Remaining process-capture elicitation work continues in #96.
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
main
codex/procedure-reference-stacked
release-please--branches--main--components--rea-agents
release-please--branches--main--components--rea-agents--release-notes
codex/kuna-independent-retry
codex/byte-search-overlay-coverage
codex/open-failure-target-receipt
codex/kuna-xref-evidence
codex/ghidra-ambiguous-procedure-recovery
codex/function-source-bundle
codex/trace-function-integration-prototype
codex/snapshot-source-closure
codex/recorded-evidence-array-pages
codex/evidence-recovery-redesign
codex/trace-feature-address-scope
codex/call-discovery-scope
codex/ghidra-literal-candidate-evidence
codex/decompile-directory-independent-retry
codex/retry-provenance-base
codex/value-flow-capability-experiment
codex/ghidra-containing-instruction
cursor/readme-discord-button-ef9f
dependabot/github_actions/actions/setup-node-7.1.0
dependabot/github_actions/actions/upload-artifact-7.0.2
dependabot/npm_and_yarn/npm-minor-and-patch-d8d97ce6df
codex/kuna-1989
fix/8559-native-ui-fixture-ownership
fix/8555-go-verifier-mcp-ownership
codex/provider-capability-recovery
fix/8642-rizin-target-stdin
codex/ghidra-memory-effect-scope
codex/ghidra-annotation-entry-selector
codex/ghidra-readonly-recovery
codex/ghidra-regex-verifier-recovery
codex/evidence-discovery-view-guidance
fix/8545-bulk-append-overflow
fix/8428-navigation-refusal-alternatives
codex/address-context-recovery
codex/matching-member-limitations
codex/unknown-scope-contract
codex/evidence-view-guidance
feat/8373-native-trace-views
codex/ghidra-snapshot-verifier-binding
codex/elf-export-visibility
codex/evidence-view-recovery
codex/native-reference-cli-help
codex/provider-candidate-observation-scope
codex/kuna-session-verification
codex/ghidra-switch-lifetime-guidance
codex/pseudocode-paging-discovery
codex/clarify-evidence-view-support
codex/kuna-xrefs-selector-recovery
codex/context-capacity-recovery
codex/evidence-closure-large-links
codex/same-function-evidence-identity
codex/ghidra-verifier-inspected-jdk
codex/audit-guided-workflows
codex/crash-prompt-retained-dossiers
codex/analysis-view-error-recovery
codex/kuna-verifier-target-selection
codex/ghidra-selected-project-call-coverage
codex/docs-native-analysis-scope
codex/ghidra-java-socket-boundary
codex/ghidra-retained-snapshot-verifier
codex/ghidra-search-inventory-facts
fix/8284-zero-argument-parameter-bindings
fix/8198-ui-action-handler-offset
fix/8257-elf-entry-label-identity
fix/8304-deferred-output-schema-projection
fix/8277-call-path-computed-target-uncertainty
fix/pr-8089-conflicts
fix/ci-static-duplicate-export
dependabot/npm_and_yarn/lint-staged-17.6.0
dependabot/github_actions/actions/download-artifact-8.0.2
dependabot/npm_and_yarn/write-file-atomic-8.0.0
dependabot/npm_and_yarn/canonicalize-5.1.0
dependabot/github_actions/actions/cache/restore-6.1.0
dependabot/npm_and_yarn/toon-format/toon-4.4.0
dependabot/github_actions/actions/deploy-pages-5.0.1
codex/review-fixes-pr-2403
codex/review-fixes-pr-2400
codex/process-terminal-width
codex/test-brittleness-cleanup
verify/7167-browser-connect-macos
fix/7167-browser-connect
feat/native-matching-allowance-setting
feat/browser-scenario-dry-run
test/managed-caller-parameters-20261024
codex/parser-fortythird-boundaries
fix/6926-pinvoke-platform-decorations-20261023
fix/6889-har-body-encoding-20261023
fix/6888-sqlite-schema-budget-20261023
fix/dependency-security-gates-6708
cursor/evidence-overwrite-rebase-b4ac
feat/4057-verify-native-exports
fix/windows-acl-observer-overhead-20261022
cursor/erlang-beam-restack-4476
cursor/pe-certificate-review-bf32
fix/6116-javascript-application-fs-errors
fix/6061-unmapped-runtime-script-unknown
feat/browser-scenario-summary
fix/pe-certificates
codex/verify-3407
cursor/rebase-5699
cursor/rebase-5352
cursor/rebase-5600
cursor/fix-cli-schema-omission-10a8
codex/audit-hopper-shutdown-reasons-20261021
fix/demangle-swift-omitted-record
fix/nib-boolean-value-types
cursor/cancellation-partial-observation-a5ac
fix/ib-object-limit-reasons
fix/electron-fuse-limit-advice
fix/kuna-doctor-dangling-cache
fix/fixed-budget-refusal-advice
fix/js-ipc-listener-dedup
fix/js-return-member-provenance
fix/dmg-integrity-retry-advice
fix/ida-doctor-readiness
fix/kuna-version-probe-output-drain
fix/legacy-swift-runtime-name-matching
fix/dylib-lazy-load-commands
fix/browser-scenario-startup-cancel
fix/swift-nested-punycode-classification
fix/compare-unselected-scopes
fix/objc-method-budget-coverage
fix/dmg-mounted-root-observations
audit/ci-tests-20261019-round2
release/6.7.0
fix/wabt-cleanup-retry-resolution
fix/electron-fuse-elf-pe-architecture
fix/native-plist-descriptor-ownership
fix/kuna-caller-cleanup-ownership
experiment/atomic-codemode-20261016
review/first-contributor-3776
fix/call-resolution-full-read-cycles
fix/member-mutation-selection-repeat
experiment/atomic-re-tools-20261015
perf/member-mutation-lazy-origins
perf/static-network-mutation-index
fix/hopper-startup-lifecycle
audit/3050-windows-proof-20261015
feat/windows-window-capture-2183
audit/3049-windows-proof-20261015
audit/3735-macos-fixtures-20261015
fix/batch-decompile-null-pseudocode
fix/kuna-inventory-honors-jobs
experiment/browser-codemode-tool-design-20261015
fix/hopper-clean-runtime-argv
codex/review-2049-27f1b367
review-fixes/pr-2787-routing
fix/3360-scoped-this-emitters
fix/3367-replaced-global-effects
fix/3838-compact-any-value-items
test/hopper-download-probe-20261015
codex/windows-runtime-creation-red-green-20261015
codex/windows-readonly-root-red-green-20261015
codex/windows-root-share-red-green-20261015
codex/exp-1685-win-mcp-startup
codex/bug-sweep-20261015
investigate/2190-windows-package-phases
investigate/3543-macos-cli-deadline
perf/3281-reverse-tools-feedback-quality
fix/3406-hopper-doctor-fixture
fix/3341-wrapper-require-test-context
fix/3301-owned-uninstall-fixtures
fix/3164-compiler-input-ownership
fix/pcap-cleanup-stdout-newline-20261014
perf/interface-builder-summary
codex/review-fixes-pr-1977
fix/ghidra-effective-jvm-platform
fix/docs-turkish-rust-link-20261013
fix/main-maintenance-ci-20261010
fix/recover-binary-session-process-effects
codex/review-fixes-pr-2457
codex/ci-required-cancellation-gate
fix/main-format-baseline-20261013
fix/setup-preserve-entry-fields
cursor/restore-main-checks-1ffc
fix/ghidra-bridge-hashmap-import
codex/shared-ci-jadx-json-default-20261013
codex/shared-ci-ghidra-test-groups-20261013
codex/shared-ci-java-fixture-format-20261013
codex/fix-intrinsic-invocation-boundaries
test/release-preflight-reusable-jobs
test/js-parameter-provenance-expectation
fix/linux-hopper-verification-current
test/2419-ghidra-elf-probe-size
followup/pr-1544-native-ida
codex/fold-pr-2230-contribution
docs/readme-responsible-use
fix/issue-2064
fix/issue-2050
fix/issue-2053
fix/issue-1968
fix/issue-1945
experiment/codemode-bridge-20261011
fix/tool-effects-negative-wording-1904-20261012
fix/1842-electron-interop-provenance
feat/recover-javascript-multi-input
refactor/website-i18n-prep
fix/nativeaot-pe-virtual-extent
fix/browser-verifier-ci-hang
fix/pe-resources-input-selection
docs/beginner-friendly-guides
docs/beginner-setup-guide
fix/javascript-analysis-worker-1563
fix/1649-ghidra-duplicate-names
fix/javascript-export-keys-integration-1369
test/maintenance-boundary-contracts-20261011
review/javascript-export-keys-1369
review/process-live-progress-1483
test/javascript-1495-growth-ratio
fix/ci-escape-timing
docs/normalized-terminal-geometry-1450
release/6.3.0
archive/release-6.3.0-pr1381
release/6.2.0
fix/electron-preload-dynamic-override
fix/javascript-self-referential-bundler-edges
release/6.1.0
cursor/grok-client-cherry-pick-0b56
feat/signature-posture
feat/dyld-shared-cache
feat/artifact-integrity-policy
feat/pkg-inventory
release/6.0.0
chore/sync-release-5.0.0
release/5.0.0
cursor/cloud-agent-node-787e
fix/javascript-xhr-open-endpoints
review/pr-711-realpath-fallback-wording
cleanup/replay-confinement
codex/test-suite-performance
codex/issue-foundations
codex/address-open-issues-2026-07-20
agent/javascript-vite-rollup-esbuild-adapters
agent/process-cleanup
agent/triage-integration
agent/unknown-commands-registry
feat/mcp-identity-metadata
morlvps/issue_cleanup
codex/installer-redesign
morl/roadmap-investigation-core
morl/roadmap-investigation-docs
release-please--branches--main--components--rea
rea-agents-6.8.0
rea-agents-6.7.0
rea-agents-6.6.0
experiment/atomic-codemode-wait-runtime-20261016
rea-agents-6.5.0
rea-agents-6.4.0
rea-agents-6.3.0
rea-agents-6.2.0
rea-agents-6.1.0
rea-agents-6.0.0
rea-agents-5.0.0
rea-agents-4.1.0
rea-agents-4.0.1
rea-agents-4.0.0
rea-agents-3.2.1
rea-agents-3.2.0
rea-agents-3.1.0
rea-agents-3.0.0
rea-agents-2.7.0
rea-agents-2.6.0
rea-agents-2.5.1
rea-agents-2.5.0
rea-agents-2.4.0
rea-agents-2.3.0
rea-agents-2.2.0
rea-agents-2.1.0
rea-agents-2.0.0
rea-agents-1.7.0
rea-agents-1.6.0
rea-agents-1.5.0
rea-agents-1.4.0
rea-agents-1.3.0
rea-agents-1.2.0
rea-agents-1.1.0
rea-agents-1.0.0
rea-agents-0.5.0
rea-agents-0.4.0
rea-agents-0.3.0
rea-0.2.1
rea-0.2.0
Labels
Clear labels   
area: bridge

   
area: bridge

   
area: build

   
area: build

   
area: build

   
area: cli

   
area: domain

   
area: evidence

   
area: mcp

   
area: native

   
area: providers

   
area: runtime

   
area: server

   
area: setup

   
area: tests

   
bug

   
design

   
documentation

   
enhancement

   
enhancement

   
enhancement

   
experiment

   
help wanted

   
i18n

   
invalid

   
P0: critical

   
P1: high

   
P2: medium

   
P2: medium

   
P2: medium

   
P3: low

   
performance

   
provider-request

   
pull-request
Mirrored from GitHub Pull Request

  
question

   
roadmap

   
triage
No labels
area: bridge
area: bridge
area: build
area: build
area: build
area: cli
area: domain
area: evidence
area: mcp
area: native
area: providers
area: runtime
area: server
area: setup
area: tests
bug
design
documentation
enhancement
enhancement
enhancement
experiment
help wanted
i18n
invalid
P0: critical
P1: high
P2: medium
P2: medium
P2: medium
P3: low
performance
provider-request
pull-request
question
roadmap
triage
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
morluto/rea#73
No description provided.