Metadata-Version: 2.4
Name: strands-stigmer
Version: 0.5.0
Summary: The execution graph of AWS for Strands agents. Call chains, traps, least-privilege IAM policies, pre-flight authorization, a pre-action hook, and a scoped use_aws.
License: Apache-2.0
Project-URL: Homepage, https://stigmer.network
Project-URL: Source, https://github.com/LNSHRIVAS/stigmer
Keywords: aws,mcp,agents,strands,iam,boto3
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: strands-agents>=0.1
Requires-Dist: mcp>=1.0
Dynamic: license-file

# strands-stigmer

The execution graph of AWS for [Strands](https://strandsagents.com) 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](https://stigmer.network), an open MCP knowledge network with 30,000+ contracts across 380 services.

## Install

```bash
pip install strands-stigmer
```

## Usage

```python
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:

```python
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](https://stigmer.network)
- [MCP endpoint](https://stigmer.network/mcp)
- [Agent self-onboarding](https://stigmer.network/llms.txt)

## License

Apache-2.0
