strands-stigmer

The execution graph of AWS for Strands agents.

A single toolset that gives your agent verified AWS method contracts (required params, IAM permissions, pagination contracts, call-chain links, and known traps), a least-privilege IAM policy generator for multi-step workflows, a pre-flight authorization check that asks AWS's own policy simulator whether an operation is allowed before it executes, a pre-action authorization hook that blocks denied tool calls before they run, and a scoped use_aws that runs each call against an assumed role bounded by a least-privilege session policy.

Backed by Stigmer, an open MCP knowledge network with 30,000+ contracts across 380 services.

Install

pip install strands-stigmer

Usage

from strands import Agent
from strands_stigmer import stigmer_query, stigmer_policy, stigmer_authorize
from strands_stigmer.hooks import StigmerAuthHook

agent = Agent(
    tools=[stigmer_query, stigmer_policy, stigmer_authorize],
    hooks=[StigmerAuthHook()],
)

# Generate a least-privilege IAM policy for a workflow
agent("Generate the least-privilege policy for an S3 multipart upload with KMS encryption")

# Pre-flight check: is s3:PutObject allowed for the current role?
agent("Before you call S3, check whether I'm authorized to put objects")

Every use_aws tool call is now checked before execution. If AWS's own policy simulator reports the current identity is denied, the call is cancelled with the missing permissions listed. When the simulator cannot answer (unknown), the call passes through by default; pass StigmerAuthHook(fail_closed=True) to block unverifiable calls too.

Tools

stigmer_policy(workflow="", operations="", description="")

• Generate a least-privilege IAM policy. Pass one of:
  • workflow - a named workflow (see stigmer_list_workflows)
  • operations - explicit IAM actions or SDK symbols, comma-separated
  • description - describe the workflow in plain language
• Returns: paste-ready policy grouped by service, with confidence tier and any unresolved operations

stigmer_authorize(operations="", workflow="", principal_arn="")

• Pre-flight authorization check. Resolves the IAM actions an operation requires, then asks AWS's own policy simulator (SimulatePrincipalPolicy) whether the current role (or a given principal) allows them
• Returns resolution (exact|partial|unresolved) and evaluation (allowed|denied|unknown) as separate fields, plus missing_permissions and the simulator's documented caveats
• evaluation is populated only when the calling environment has AWS credentials; otherwise it is unknown with the reason

stigmer_verify(workflow="", operations="", policy="")

• Feed a generated policy back to AWS's own evaluator (SimulateCustomPolicy) and confirm it grants exactly the intended operations and nothing extra
• Returns verified (True|False|unknown), grants_all, and grants_extra
• verified is populated only when the calling environment has AWS credentials

stigmer_list_workflows()

• List the curated named workflows available for policy generation

stigmer_query(query, library="")

• Search verified method contracts: required params, IAM permissions, pagination contract, call-chain links, and known traps
• library scopes to one SDK: "boto3" or "aws-sdk-js"

StigmerAuthHook(fail_closed=False)

• A BeforeToolCallEvent hook that authorizes AWS tool calls before they execute
• For each use_aws call, resolves the operation to its required IAM actions and asks AWS's own simulator whether the current identity allows them
• evaluation: denied cancels the call and lists the missing permissions; allowed passes through; unknown passes through by default, or blocks when fail_closed=True
• Covers any tool, not just use_aws; no upstream changes or approval required

stigmer_use_aws(service_name, operation_name, parameters={}, region="us-west-2", profile_name=None, role_arn=None, session_policy=None)

• A drop-in replacement for use_aws that adds per-call credential scoping
• With role_arn + session_policy, the call runs against an sts:AssumeRole session whose effective permissions are the intersection of the role's policies and the supplied least-privilege policy
• Without them, it behaves exactly like use_aws (ambient session)
• session_policy without role_arn raises a clear error: the ambient session is fixed at process launch and cannot be narrowed, so scoping requires an assumed role
• This is the working demonstration of the use_aws feature request (strands-agents/tools#337 follow-up): scoping plumbed into the tool instead of a racy temp-profile workaround

Write back

Stigmer grows from agent contributions. If your agent hits a trap not in the network, register it so the next agent walks around it:

from strands import tool

@tool
def stigmer_register(action: str, symbol: str, error: str, fix: str) -> str:
    """Register a fix with Stigmer. action: 'confirm' | 'append_thread' | 'new_receipt'."""
    # Posts to the Stigmer MCP endpoint; see https://stigmer.network/mcp
    ...

Docs

• Stigmer
• MCP endpoint
• Agent self-onboarding

License

Apache-2.0