Terminal
Terminal/Skill
Traces why a Bedrock or SageMaker call is denied, names the step that blocked it, and proposes a scoped policy without changing anything.
By Amazon Web Services
Works with
npx skills add aws/tools-for-devops-agent --skill aiml-access-diagnosticsDiagnose why an AI/ML service call was denied. Walk the authorization chain hop by hop, name the hop that denied the call, and propose a scoped IAM policy for human review. Read-only throughout.
Work through these steps in order. Each is detailed in its own section below.
The report is the deliverable. Conversation around it is not.
| Service | Coverage |
|---|---|
| Amazon Bedrock | Full — including non-IAM denial causes |
| Amazon SageMaker | Full — including PassRole and execution-role chains |
| Other AI/ML services | Not supported in this version. State this plainly and stop. |
If the request concerns an unsupported service, say so and do not attempt a partial diagnosis from the generic chain alone. The value of this skill is in the service-specific knowledge; without it the output would be a guess.
references/access-chain-model.mdreferences/data-collection.mdreferences/finding-logic.mdreferences/report-format.mdreferences/svc-bedrock.md,
references/svc-sagemaker.mdClassify before calling any tool. Two things must be established first.
Determine the AI/ML service from the error text, API name, or resource ARN. If it is not Bedrock or SageMaker, stop and report it as unsupported.
| Evidence available | Route |
|---|---|
| User pasted an error message | Observed — parse it, then corroborate with CloudTrail |
| No error text, but a principal and action are named | Observed — locate the event in CloudTrail |
| Neither | Stop. Ask for the error message, or the principal ARN plus the API call that failed. |
This skill diagnoses failures. It does not audit permissions speculatively. If there is no failure to explain, say so and stop rather than producing a posture review.
sts:GetCallerIdentity to determine the account and the identity the agent
itself is operating as. Record it — the report must state whose view this is.User: <arn> is not authorized to perform: <action> on resource: <arn> carry all
three.references/finding-logic.md.Policy documents are the primary evidence. Every hop except the organization SCP
decision is decidable by reading the policies that govern it. CloudTrail and the policy
simulator are corroboration, and the diagnosis must stand without either — in this runtime
both are frequently unavailable, which is a characteristic of the environment rather than a
permission gap. See references/data-collection.md.
Collect in this order:
requestParameters — the passed RoleArn and any VpcConfig,
neither of which appears in the error string.references/svc-bedrock.md for the Bedrock grant event names. Without CloudTrail,
propagation cannot be ruled out; say so rather than ruling it out.AllowedByOrganizations at hop 6. It cannot evaluate trust policies at
all, and at hop 2 it is measurably wrong on correctly configured callers unless
iam:PassedToService is supplied.Where a policy read and simulation disagree, the policy read wins, except for
AllowedByOrganizations.
If a collection step fails, record its status, distinguishing an unreadable policy from an operation the runtime does not permit. Never infer a configuration you could not read, and never infer one operation's availability from another's failure.
Traverse the six hops in the order defined in
references/access-chain-model.md. Stop descending once a hop produces a definitive
DENIED_BY, but still collect and report the remaining hops as context where the
data is already in hand.
The most common outcome is that the caller's permissions are fine and the service role's permissions are not. Do not conclude at hop 1 simply because it passed.
Load the matching references/svc-*.md and evaluate the non-IAM denial causes it
lists. For Bedrock these include model subscription state, AWS Marketplace
permissions, and propagation timing — none of which are IAM policy gaps, and all of
which produce AccessDeniedException.
A diagnosis that checks only IAM and reports "your permissions are correct" while one of these is the true cause is the primary failure mode of this skill. Rule them out explicitly.
Every hop gets exactly one token from this closed set. Definitions and assignment rules
are in references/finding-logic.md. Never invent a token, and never write a verdict as
free prose in place of one.
| Verdict | Meaning |
|---|---|
DENIED_BY | This hop denied the call, with evidence |
WOULD_ALSO_DENY | This hop would deny too, but an earlier hop is the operative cause |
ALLOWED_BUT_UNVERIFIABLE | Evidence suggests allow, but something outside our view could still deny |
CANNOT_DETERMINE | Required evidence was unavailable — names what was missing |
NOT_APPLICABLE | The call shape does not include this hop |
NOT_EVALUATED | An earlier hop denied and this hop's evidence was not collected |
Never collapse ALLOWED_BUT_UNVERIFIABLE into an allow. Readable policies indicating
an allow is not proof the live call succeeds.
Use WOULD_ALSO_DENY rather than contradicting yourself. If a hop below the root cause
independently shows a denial, mark it as such. A hop whose finding says the call will fail
must never appear in the chain table as allowing it.
Produce a policy document for human review. Two categories of permission, labelled distinctly and never merged:
| Category | Source | Label in report |
|---|---|---|
| Hop-1 permissions | The action and resource from the observed CloudTrail failure | "Derived from the observed failure" |
| Hop-2 permissions | Curated per-service minimums from references/svc-*.md | "Commonly required — not observed; verify against your workload" |
The simulator does not generate policies. It attributes decisions. Do not present simulator output as a suggested policy.
Render per references/report-format.md, run the pre-render validation, then deliver.
Every step degrades gracefully. A single failed read never aborts the diagnosis — log it, mark the affected hop, and continue with what remains.
| Condition | Cause | Action |
|---|---|---|
iam:SimulatePrincipalPolicy refused by the runtime | The environment does not permit this operation. It is not an IAM gap — the action sits inside the agent's permission guardrail and can be granted in IAM while remaining uncallable. | Proceed on policy reads, which decide hops 1 through 5 regardless. Emit the runtime-restriction notice. Never report it as "not granted" and never recommend a policy change, CloudFormation template, or role edit — no such fix exists. Note only that AllowedByOrganizations could not be computed. |
cloudtrail:LookupEvents refused or deferred by the runtime | Same — classified as requiring operator approval despite being read-only | Proceed on the user-supplied error text and policy reads. Emit the runtime-restriction notice. Do not stall waiting for approval, do not retry in a loop, and do not report it as a permission gap. State that the event was not corroborated and that propagation could not be ruled out. |
AccessDenied on any other read | The agent's IAM genuinely lacks that permission | Mark the affected hop CANNOT_DETERMINE, naming the operation, and emit the agent-IAM-gap notice — this one a grant would fix. Continue. |
| One read refused | Says nothing about other operations | Still attempt every other read the hops require. Never infer a second operation's availability from the first one's failure. |
| No CloudTrail event found | Delivery lag of up to ~15 minutes, or wrong region or time window | Proceed using the user-supplied error text. State that the event was not corroborated. Do not conclude the call never happened. |
| Neither error text nor CloudTrail event | Nothing to diagnose | Stop. Ask for the error message, or the principal ARN plus the failed API call. |
| Target role cannot be identified | RoleArn absent from the event and no Describe available | Mark hops 2 through 4 CANNOT_DETERMINE. Do not diagnose hop 1 alone and imply the chain is clear. |
| Service is not Bedrock or SageMaker | Out of scope for this version | Stop and report it as unsupported. Do not attempt a generic diagnosis. |
| Account is not in an Organization | No SCP applies | Mark hop 6 NOT_APPLICABLE. This is not a failure. |
| Simulation contradicts a policy read | Simulation is a model and has known blind spots — trust policies, and iam:PassRole conditions | Follow the policy read. State the divergence and which one the verdict followed. Do not mark the hop CANNOT_DETERMINE on this basis alone. |
| CloudTrail shows a denial the policies read as allowing | The cause lies outside the readable policies — a session policy, a conditional SCP, or a service-side gate | Mark the hop CANNOT_DETERMINE and surface the divergence — it is itself the finding. |
| Request is a permissions audit with no failure | Out of scope; this skill is reactive | Say so and stop. Do not produce a posture review. |
references/report-format.md. If the runtime supports
persisted artifacts, also write it as
aiml-access-diagnosis-<service>-<YYYY-MM-DD>.md; if not, skip the artifact.references/data-collection.md may be called. Never call any Put*, Attach*,
Create*, Update*, or Delete* action. Never apply a proposed policy. Note that
write prevention is ultimately enforced by the DevOps Agent permission guardrail and the
agent role's IAM permissions, not by this instruction — but the instruction is binding
regardless.CANNOT_DETERMINE naming the gap.CANNOT_DETERMINE, not an inherited answer.AllowedByOrganizations at hop 6, which policy reading cannot compute.cloudtrail:LookupEvents and
iam:SimulatePrincipalPolicy are refused by this runtime while permitted in IAM.
Reporting either as "not granted", or proposing a policy or CloudFormation change to
obtain them, is a false remediation. This skill requires no IAM changes.iam:PassRole and the
role's trust policy allowing the service principal are different problems with
nearly identical symptoms.references/access-chain-model.md — the six-hop chain, precedence, and traversal rulesreferences/data-collection.md — API allowlist, error classification, output schemareferences/finding-logic.md — verdict rules and body templatesreferences/report-format.md — report structure and pre-render validationreferences/svc-bedrock.md — Bedrock roles, actions, and non-IAM denial causesreferences/svc-sagemaker.md — SageMaker PassRole, trust policy, and execution-role minimums