Skip to Content
AgentSecurity and troubleshooting

Security model

  • No credentials for the agent. pf passes only --profile <name> to the aws CLI. The credentials stay with the AWS CLI and SSO, and pf never reads, prints or stores them.
  • Approval outside the model. A grant needs your answer in a dialog. No tool argument can approve one.
  • Two layers of limits. Your profile caps what can be asked for, and a repo can only narrow it. Inside a grant, every call is checked for operation, scope, region, parameters and account.
  • Fail closed. No grant, no read. A wrong account means nothing is read. With no dialog and a client that runs the tool unasked, the grant is refused.
  • Short-lived. Grants last minutes, end with the session, and can be revoked from another terminal.
  • Traceable. Every request, decision, call and refusal is logged per session in ~/.pf/agent/audit/.
  • Defense in depth. Point each profile at a read-only IAM role (ViewOnlyAccess, or tighter), so AWS refuses writes even if pf had a bug.
  • Fixes are separate and stricter. pf_aws_act runs only actions your profile enables, with listed flags, on a pinned account, and only after you approve that exact command in pf’s dialog. It never falls back to the agent CLI’s own prompt.
  • Only registered profiles. pf uses an AWS profile only when it is in pf’s registry (~/.pf/config.json). Linking one to a repo needs your pick and approval.
  • Staging only. The agent and MCP tools deploy to staging only. A staging deploy returns a plan until the call passes confirm, and the agent CLI asks first.

Limits to keep in mind:

  • Read-only metadata can still be sensitive: resource names, IPs, tags, and log lines with the logs scope.
  • Redaction catches common patterns only.
  • A repo’s pulpfixer.json chooses which of your profiles applies. The dialog always names the profile, its source and the account, so read it before approving.

Troubleshooting

SymptomCause and fix
No pf profile applies hereAdd one (pf profile add) and name it in pulpfixer.json, or set a default with pf profile use
The profile "x" ... is not configuredpulpfixer.json names a profile this machine does not have: pf profile add x ...
has no AWS profilepf profile add x --aws-profile <name>
The dialog never shows; the grant says could not ask the userthe agent CLI lacks MCP elicitation, or this is claude -p. Update the CLI, or run the agent interactively
aws ... is not enabled for this profilethe action is off for this profile: pf profile add <name> --actions "<service> <operation>", or run the change yourself
Fix actions need a pinned accountpf profile add <name> --account <id>
No AWS profiles are available (link dialog)pf has no profiles and ~/.aws/config lists none: aws configure sso, then pf t --link
This is not the pinned accountthe AWS profile resolves to another account, often after an SSO login to another account. Check with pf profile check, fix ~/.aws/config or log in again
aws ... failed: ... ExpiredToken or SSO session expiredaws sso login --profile <aws-profile>
aws CLI not found on PATHinstall the aws CLI v2
Output cutnarrow the call with query, filters, max-items or a shorter time range
The agent keeps the old profilethe server re-reads ~/.pf/config.json and pulpfixer.json before each tool call, so an edit applies on the next call. --profile and PF_PROFILE still win over pulpfixer.json for that session
Check what the agent didlist ~/.pf/agent/audit/ newest first, then read the latest log
Last updated on