iam-policy-validator 1.15.4__tar.gz → 1.15.6__tar.gz

{iam_policy_validator-1.15.4 → iam_policy_validator-1.15.6}/.gitignore

@@ -87,3 +87,4 @@ aws_services/
 
 .mcp.json
 .serena
+agent-sync/

{iam_policy_validator-1.15.4 → iam_policy_validator-1.15.6}/CHANGELOG.md

@@ -13,6 +13,37 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [1.15.5] - 2025-01-28
+
+### Fixed
+
+**Shell Completions**
+
+- Remove `--instructions` and `--instructions-file` from `iam-validator mcp` subcommand completions
+  - These options only exist in the standalone `iam-validator-mcp` command, not the subcommand
+
+**SDK Context Manager**
+
+- Fix `validator()` and `validator_from_config()` to properly initialize and cleanup `AWSServiceFetcher`
+  - Now uses `async with` for correct HTTP client lifecycle management
+  - Ensures connections are properly closed when context exits
+
+**SDK Shortcuts**
+
+- Remove unused `config` parameter from validation functions (`validate_file`, `validate_directory`, `validate_json`, `quick_validate`, `get_issues`, `count_issues_by_severity`)
+- Fix `recursive` parameter in `validate_directory()` to actually be passed to `PolicyLoader.load_from_path()`
+
+### Documentation
+
+- Update MCP tool count from "25+" to "35" and document 7 missing tools
+- Expand SDK API reference with ARN utilities, query utilities, and policy utilities
+- Add all 17 `ValidationIssue` fields to documentation
+- Add SDK installation extras (`[mcp]`, `[dev]`, `[docs]`)
+- Add output format examples with sample outputs for JSON, SARIF, Markdown, HTML, CSV
+- Expand configuration reference with global settings, check options, environment variables
+
+---
+
 ## [1.15.4] - 2025-01-27
 
 ### Fixed

{iam_policy_validator-1.15.4 → iam_policy_validator-1.15.6}/CONTRIBUTING.md

@@ -59,6 +59,44 @@ iam_validator/
 - **New Command**: Add to `iam_validator/commands/`
 - **New Formatter**: Add to `iam_validator/core/formatters/`
 
+## MCP Tool Docstring Guidelines
+
+When adding or modifying MCP tools in `iam_validator/mcp/server.py`, follow this template:
+
+```python
+@mcp.tool()
+async def tool_name(
+    param1: str,
+    param2: bool = False,
+) -> dict[str, Any]:
+    """One-sentence description of what the tool does.
+
+    [Optional: One line of critical context]
+
+    Args:
+        param1: Description (e.g., "s3:GetObject")
+        param2: Description
+
+    Returns:
+        {field1, field2, field3}
+    """
+```
+
+### Rules
+
+- **Max 300 tokens** per tool docstring (~1200 characters)
+- **Always include format hints** for IAM actions: `(e.g., "s3:GetObject")`
+- **Use simple field lists** for Returns, not nested structures
+- **Don't repeat** BASE_INSTRUCTIONS content in tool docstrings
+- **Keep first sentence descriptive** - it's crucial for tool discovery
+
+### Token Limits
+
+| Component | Max Tokens |
+|-----------|------------|
+| Tool docstring | 300 |
+| BASE_INSTRUCTIONS | 2500 |
+
 ## Getting Help
 
 - [GitHub Issues](https://github.com/boogy/iam-policy-validator/issues)

{iam_policy_validator-1.15.4 → iam_policy_validator-1.15.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: iam-policy-validator
-Version: 1.15.4
+Version: 1.15.6
 Summary: Validate AWS IAM policies for correctness and security using AWS Service Reference API
 Project-URL: Homepage, https://github.com/boogy/iam-policy-validator
 Project-URL: Documentation, https://boogy.github.io/iam-policy-validator

{iam_policy_validator-1.15.4 → iam_policy_validator-1.15.6}/docs/api-reference/models.md

@@ -43,19 +43,30 @@ Represents a validation issue found in a policy.
 
 ```python
 class ValidationIssue(BaseModel):
+    # Core fields
     severity: str              # error, warning, critical, high, medium, low
     statement_index: int       # Statement number (0-based)
-    issue_type: str            # Issue category
+    issue_type: str            # Issue category (e.g., "invalid_action", "overly_permissive")
     message: str               # Human-readable description
-    check_id: str | None       # Check that found this
-    statement_sid: str | None  # Statement ID
-    action: str | None         # Action involved
-    resource: str | None       # Resource involved
-    condition_key: str | None  # Condition key involved
-    suggestion: str | None     # How to fix
-    example: str | None        # Code example
-    line_number: int | None    # Line in source file
-    field_name: str | None     # Field name (action, resource, etc.)
+    check_id: str | None       # Check that found this (e.g., "wildcard_action")
+    statement_sid: str | None  # Statement ID if present
+
+    # Context fields
+    action: str | None         # Action involved in the issue
+    resource: str | None       # Resource involved in the issue
+    condition_key: str | None  # Condition key involved in the issue
+    field_name: str | None     # Field name: "action", "resource", "condition", "principal", "effect", "sid"
+    line_number: int | None    # Line number in source file
+
+    # Guidance fields
+    suggestion: str | None     # How to fix the issue
+    example: str | None        # Code example (JSON/YAML)
+
+    # Enhanced finding quality fields
+    risk_explanation: str | None      # Why this is a security risk
+    documentation_url: str | None     # Link to AWS docs or runbook
+    remediation_steps: list[str] | None  # Step-by-step fix guidance
+    risk_category: str | None         # Category: "privilege_escalation", "data_exfiltration", etc.
 ```
 
 ## PolicyValidationResult