Skip to content

fix(gateway): refuse a bound NONE gateway in a Box project, explain a 403 - #2888

Open
vvargu wants to merge 1 commit into
box-integrationfrom
fix/box-gateway-resource-policy-cli
Open

vvargu wants to merge 1 commit into
box-integrationfrom
fix/box-gateway-resource-policy-cli

Conversation

@vvargu

@vvargu vvargu commented Nov 21, 2026

Copy link
Copy Markdown

Description

Companion to aws/agentcore-l3-cdk-constructs#476 (AppSec H3). That change gives each Box gateway a resource policy that
lets only its runtime's execution role invoke it. This PR does the two CLI parts of the #476 review:

  • Schema. The project schema refuses authorizerType: "NONE" on a gateway with boundRuntime in a Box project. A
    Box gateway holds its runtime's outbound credentials, and with NONE anyone with its URL could call it. The L3 schema
    has the same check and the same message. The CLI writes AWS_IAM for each Box gateway, so only a hand edit hits it.
  • agentcore gateway invoke. An HTTP 403 from an AWS_IAM gateway now comes with a hint. The resource policy
    denies every other principal, so a developer's own credentials get AccessDenied on a Box gateway, even with
    administrator access. The command line writes the hint to stderr. The TUI shows it as the note of the failed
    exchange. Outside a Box project, a bound gateway gets no resource policy, so gateway invoke there works as before.

Testing

  • bun run typecheck, bun run lint:check and bun run format:check pass.
  • bun test: 5839 pass, 1 fail. The failure is
    the box on PATH > resolves a profile into the rules the tests fake. It runs the local box binary, which rejects the
    test profile ("@box/base" is not a pack name). It does not touch the files in this PR.
  • New tests: the schema refuses a bound NONE gateway in a Box project and accepts one outside it. gateway invoke
    writes the hint for a 403 from an AWS_IAM gateway, and no hint for a 403 from a NONE gateway.

… 403

Companion to aws/agentcore-l3-cdk-constructs#476. That change gives
each Box gateway a resource policy that lets only its runtime's
execution role invoke it.

The project schema now refuses authorizerType "NONE" on a gateway with
boundRuntime in a Box project. A Box gateway holds its runtime's
outbound credentials, and with NONE anyone with its URL could call it.
The L3 schema has the same check and the same message. The CLI writes
AWS_IAM for each Box gateway, so only a hand edit hits this.

`agentcore gateway invoke` now explains an HTTP 403 from an AWS_IAM
gateway. The resource policy denies every other principal, so a
developer's own credentials get AccessDenied on a Box gateway, even
with administrator access. The command line writes the hint to stderr,
and the TUI shows it as the note of the failed exchange.
@vvargu
vvargu requested a review from a team November 21, 2026 01:40
@codecov-commenter

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.80%. Comparing base (e2ac9d7) to head (641577f).
⚠️ Report is 12 commits behind head on box-integration.

Additional details and impacted files
@@               Coverage Diff                @@
##           box-integration    #2888   +/-   ##
================================================
  Coverage            96.79%   96.80%           
================================================
  Files                  766      766           
  Lines                66803    66857   +54     
================================================
+ Hits                 64665    64719   +54     
  Misses                2138     2138           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@leo237 leo237 left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approving. CI is green: verify on Linux, Windows and macOS, CodeQL, Analyze and the e2e CodeBuild all pass. The Linux run passing also suggests the box-on-PATH failure in the body only happens locally. The branch merges cleanly with base, #2886 and #2887. I found no internal references in the diff or the commit message. Everything below is a nit.

What I checked

  • Schema. The new check uses isBoxProject(spec) (projectType === "box"), the same test the rest of the file and project dev use. Its message matches the one in aws/agentcore-l3-cdk-constructs#476 character for character. boxGatewaySpec writes AWS_IAM, and add gateway (which defaults to NONE) never sets boundRuntime, so only a hand edit can hit this. Projects the CLI wrote keep working. The test covers a bound NONE gateway in a Box project (refused), the same gateway outside a Box project (accepted), and a bound AWS_IAM gateway in a Box project (accepted).
  • Hint accuracy. #476 adds an explicit Deny on ArnNotEquals aws:PrincipalArn <runtime role>. So "even with administrator access" is correct, and limiting the hint to AWS_IAM matches #476, which gives CUSTOM_JWT gateways no IAM policy. #476 is still open and unmerged. Until it ships, the hint describes a policy that does not exist yet. It is phrased as "If this is...", so that does no harm.
  • No silent failure. In the CLI, the hint goes to stderr after the response body, and the GatewayInvokeResponseError is still thrown, so the exit code stays FAILURE (the AWS_IAM test asserts this). In the TUI, the hint takes the place of the HTTP 403 note, but the status code still shows in the Response · 403 · ... heading, so nothing is lost.
  • No new types, and the tests use none of the unsafe patterns (host paths, : splitting, POSIX modes, spawning a shell, network).

Nits (non-blocking)

  1. The hint is not limited to Box gateways. gateway invoke reads the live GetGateway response and has no project context, so every 403 from any AWS_IAM gateway gets the hint, Box or not. Because the wording is conditional ("If this is a Box Gateway ... Otherwise, check ... InvokeGateway"), this is not misleading. Still, the body's "outside a Box project ... gateway invoke there works as before" is only true of the success path. One option is to show the Box sentence only when the local project has a gateway with boundRuntime whose deployed ID matches --id. Leaving it as is also works.
  2. The hint could say how to exercise the gateway. As written, it tells a developer what fails but not what to do instead. A clause such as "To exercise it, invoke the runtime (agentcore invoke); the runtime's code calls the Gateway with its execution role" would close that gap. I would not suggest "assume the role": the execution role usually trusts only the AgentCore service principal.
  3. Test gaps (small). The NONE-403 test does not assert the exit code. Nothing tests a CUSTOM_JWT 403 (NONE covers the same branch), an AWS_IAM non-403 (for example 401 or 500), or the TUI note. A small unit test of gatewayAccessDeniedHint would cover the first three cases. Also, an unbound NONE gateway in a Box project is still accepted. I assume that is intended, since #2887's unbound NONE gateways get no outbound auth target and do not hold the runtime's credentials. A one-line test, or a note in the comment, would make that explicit.
  4. Housekeeping. This commit is not on box-integration-development yet, so it needs a back-merge after it lands. The branch is a few commits behind box-integration, with no conflicts.

Please land #476 at the same time or soon after, so the hint and the schema message describe deployed behavior.

beforeOutput,
});
if (response.statusCode < 200 || response.statusCode >= 300) {
const hint = gatewayAccessDeniedHint(response.statusCode, gateway.authorizerType);

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: this fires for every 403 from any AWS_IAM gateway, Box or not, because the command only sees the live GetGateway response. The wording is conditional, so this is fine. If you want the Box sentence only for Box gateways, you could check whether the local project has a bound gateway whose deployed ID matches --id.

): string | undefined {
if (statusCode !== 403 || authorizerType !== "AWS_IAM") return undefined;
return (
"Access denied. If this is a Box Gateway (bound to one runtime in a Box project), its " +

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: the hint says what fails but not how to test the gateway. You could add a clause like "To exercise it, invoke the runtime (agentcore invoke); the runtime's code calls the Gateway with its execution role." I would leave out "assume the role": the execution role usually trusts only the service principal, and #476's ArnNotEquals aws:PrincipalArn means only that role gets through.

runCommand(core, output.io, ["gateway", "invoke", "--id", GATEWAY_ID, "--payload", "{}"]),
);

expect(output.stderr().toString()).not.toContain("Box Gateway");

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: consider also asserting ExitCode.FAILURE here, and adding a small gatewayAccessDeniedHint unit test for CUSTOM_JWT/403 and AWS_IAM/401 or 500, both of which should return undefined.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants