iam-policy-validator 1.2.0__tar.gz → 1.5.0__tar.gz

{iam_policy_validator-1.2.0 → iam_policy_validator-1.5.0}/DOCS.md

@@ -521,8 +521,12 @@ Options:
   --batch-size BATCH_SIZE       Number of policies to process per batch (default: 10, only with --stream)
   --no-recursive                Don't recursively search directories
   --fail-on-warnings            Fail validation if warnings are found (default: only fail on errors)
-  --github-comment              Post validation results as GitHub PR comment
-  --github-review               Create line-specific review comments on PR (requires --github-comment)
+  --policy-type, -t {IDENTITY_POLICY,RESOURCE_POLICY,SERVICE_CONTROL_POLICY}
+                                Type of IAM policy being validated (default: IDENTITY_POLICY)
+                                Enables policy-type-specific validation (e.g., requiring Principal for resource policies)
+  --github-comment              Post summary comment to PR conversation
+  --github-review               Create line-specific review comments on PR files
+  --github-summary              Write summary to GitHub Actions job summary (visible in Actions tab)
   --config CONFIG, -c CONFIG    Path to configuration file (default: auto-discover iam-validator.yaml)
   --custom-checks-dir DIR       Path to directory containing custom checks for auto-discovery
   --no-registry                 Use legacy validation (disable check registry system)
@@ -544,8 +548,52 @@ iam-validator validate --path ./policies/ --format enhanced
 # Streaming mode for large policy sets
 iam-validator validate --path ./policies/ --stream
 
-# GitHub PR integration
-iam-validator validate --path ./policies/ --github-comment --github-review
+# GitHub integration - all options (PR comment + review comments + job summary)
+iam-validator validate --path ./policies/ --github-comment --github-review --github-summary
+
+# Only line-specific review comments (clean, minimal)
+iam-validator validate --path ./policies/ --github-review
+
+# Only PR summary comment
+iam-validator validate --path ./policies/ --github-comment
+
+# Only GitHub Actions job summary
+iam-validator validate --path ./policies/ --github-summary
+
+# Validate resource policies (e.g., S3 bucket policies, SNS topics)
+iam-validator validate --path ./bucket-policies/ --policy-type RESOURCE_POLICY
+```
+
+### Policy Type Validation
+
+The `--policy-type` flag enables policy-type-specific validation:
+
+**IDENTITY_POLICY** (default):
+- Policies attached to IAM users, groups, or roles
+- Should NOT contain Principal element
+- Tool warns if Principal is present
+
+**RESOURCE_POLICY**:
+- Policies attached to AWS resources (S3 buckets, SNS topics, etc.)
+- MUST contain Principal element in all statements
+- Tool errors if Principal is missing
+
+**SERVICE_CONTROL_POLICY**:
+- AWS Organizations SCPs
+- MUST NOT contain Principal element
+- Tool errors if Principal is present
+
+**Examples:**
+
+```bash
+# Validate S3 bucket policy (resource policy)
+iam-validator validate --path bucket-policy.json --policy-type RESOURCE_POLICY
+
+# Validate IAM role policy (identity policy - default)
+iam-validator validate --path role-policy.json --policy-type IDENTITY_POLICY
+
+# Validate AWS Organizations SCP
+iam-validator validate --path scp.json --policy-type SERVICE_CONTROL_POLICY
 ```
 
 ### `analyze` Command
@@ -566,8 +614,9 @@ Options:
   --output OUTPUT, -o OUTPUT    Output file path (only for json/markdown formats)
   --no-recursive                Don't recursively search directories
   --fail-on-warnings            Fail validation if warnings are found (default: only fail on errors)
-  --github-comment              Post validation results as GitHub PR comment
-  --github-review               Create line-specific review comments on PR (requires --github-comment)
+  --github-comment              Post summary comment to PR conversation
+  --github-review               Create line-specific review comments on PR files
+  --github-summary              Write summary to GitHub Actions job summary (visible in Actions tab)
   --run-all-checks              Run full validation checks if Access Analyzer passes
   --verbose, -v                 Enable verbose logging
 
@@ -617,6 +666,7 @@ Options:
   --no-review                   Don't create line-specific review comments
   --add-summary                 Add summary comment (default: True)
   --no-summary                  Don't add summary comment
+  --config, -c CONFIG           Path to configuration file (for fail_on_severity setting)
 ```
 
 **Examples:**
@@ -672,9 +722,115 @@ iam-validator cache location
 
 ---
 
+## GitHub Integration
+
+The IAM Policy Validator provides flexible GitHub integration with **three independent options** for displaying validation results:
+
+### 1. PR Summary Comment (`--github-comment`)
+
+Posts a high-level summary to the PR conversation:
+- Overall metrics (total policies, issues, severities)
+- Grouped findings by file
+- Detailed issue descriptions with suggestions and examples
+- Updated on subsequent runs (no duplicates)
+
+**Example:**
+```bash
+iam-validator validate --path ./policies/ --github-comment
+```
+
+### 2. Line-Specific Review Comments (`--github-review`)
+
+Creates inline review comments on the "Files changed" tab:
+- Comments appear directly on problematic lines in the diff
+- Includes rich context (examples, suggestions from config)
+- Automatically cleaned up on subsequent runs
+- Review status (REQUEST_CHANGES or COMMENT) based on `fail_on_severity` config
+- Works independently of `--github-comment`
+
+**Example:**
+```bash
+iam-validator validate --path ./policies/ --github-review
+```
+
+**Review Status Logic:**
+- If any issues match severities in `fail_on_severity` config → REQUEST_CHANGES
+- Otherwise → COMMENT
+- Default: REQUEST_CHANGES for `error` and `critical` severities
+
+### 3. GitHub Actions Job Summary (`--github-summary`)
+
+Writes a high-level overview to the Actions tab:
+- Visible in workflow run summary (not in PR conversation)
+- Shows key metrics and severity breakdown
+- Clean dashboard view without overwhelming details
+- Perfect for quick status checks
+
+**Example:**
+```bash
+iam-validator validate --path ./policies/ --github-summary
+```
+
+### Mix and Match Options
+
+All three options are **independent** and can be used in any combination:
+
+```bash
+# All three for maximum visibility
+iam-validator validate --path ./policies/ \
+  --github-comment \
+  --github-review \
+  --github-summary
+
+# Only line-specific review comments (clean, minimal)
+iam-validator validate --path ./policies/ --github-review
+
+# Only PR summary + Actions summary (no inline comments)
+iam-validator validate --path ./policies/ --github-comment --github-summary
+
+# Only Actions summary (no PR interaction)
+iam-validator validate --path ./policies/ --github-summary
+```
+
+### Comment Management
+
+**Automatic Cleanup:**
+- Old review comments are automatically deleted before new runs
+- Summary comments are updated (not duplicated)
+- All bot comments use HTML identifiers (invisible to users)
+
+**Streaming Mode:**
+- In CI environments, streaming is auto-enabled
+- Review comments appear progressively as files are validated
+- Provides immediate feedback during long validation runs
+
+### Required Environment Variables
+
+```yaml
+env:
+  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+  GITHUB_REPOSITORY: ${{ github.repository }}
+  GITHUB_PR_NUMBER: ${{ github.event.pull_request.number }}
+```
+
+For `--github-summary`, also requires:
+- `GITHUB_STEP_SUMMARY` (automatically provided by GitHub Actions)
+
+### Permissions
+
+Ensure your workflow has the required permissions:
+
+```yaml
+permissions:
+  contents: read
+  pull-requests: write  # Required for --github-comment and --github-review
+```
+
+---
+
 ## Configuration
 
-> **📢 Configuration Change (v1.1.0+):** The `allowed_wildcards` configuration has moved from `action_validation_check` to `security_best_practices_check` for cleaner separation of concerns. If you have a custom config file, update it accordingly. See [Migration Note](#configuration-migration) below.
+> **📢 Configuration Change (v1.1.0+):** The `allowed_wildcards` configuration has moved from `action_validation` to `security_best_practices` for cleaner separation of concerns. If you have a custom config file, update it accordingly. See [Migration Note](#configuration-migration) below.
 
 ### Configuration File
 
@@ -715,29 +871,29 @@ settings:
 # ============================================================================
 
 # Validate Statement ID (Sid) uniqueness
-sid_uniqueness_check:
+sid_uniqueness:
   enabled: true
   severity: error
 
 # Validate IAM actions against AWS service definitions
-action_validation_check:
+action_validation:
   enabled: true
   severity: error
   description: "Validates that actions exist in AWS services"
-  # Note: Wildcard security checks are handled by security_best_practices_check
+  # Note: Wildcard security checks are handled by security_best_practices
 
 # Validate condition keys
-condition_key_validation_check:
+condition_key_validation:
   enabled: true
   severity: error
 
 # Validate resource ARN format
-resource_validation_check:
+resource_validation:
   enabled: true
   severity: error
 
 # Security best practices
-security_best_practices_check:
+security_best_practices:
   enabled: true
   # Define allowed wildcard patterns for safe read-only operations
   allowed_wildcards:
@@ -767,7 +923,7 @@ security_best_practices_check:
     severity: medium
 
 # Action condition enforcement (MFA, IP restrictions, tags, etc.)
-action_condition_enforcement_check:
+action_condition_enforcement:
   enabled: true
   severity: high
 ```
@@ -793,14 +949,15 @@ By default, validation fails on `error` and `critical` severities. Use `--fail-o
 
 ### Example Configurations
 
-See [examples/configs/](examples/configs/) directory for essential configurations:
+See [examples/configs/](examples/configs/) directory for configurations:
 - `basic-config.yaml` - Minimal configuration with defaults
+- `full-reference-config.yaml` - Complete reference with all options
 - `offline-validation.yaml` - For environments without internet access
 - `strict-security.yaml` - Enterprise-grade security enforcement
-
-See [examples/configs-old/](examples/configs-old/) for additional example configurations:
-- `config-privilege-escalation.yaml` - Detect privilege escalation patterns
-- `custom-wildcard-config.yaml` - Custom wildcard action validation
+- `principal-validation-strict.yaml` - Block all public access
+- `principal-validation-relaxed.yaml` - Allow public access with conditions
+- `principal-validation-public-with-conditions.yaml` - Conditional public access
+- `principal-condition-enforcement.yaml` - Advanced principal requirements
 
 ---
 
@@ -829,7 +986,7 @@ Verifies IAM actions exist in AWS service definitions. This check focuses **sole
 ```json
 {
   "Effect": "Allow",
-  "Action": "s3:List*",  // ✅ Valid - wildcards skipped (checked by security_best_practices_check)
+  "Action": "s3:List*",  // ✅ Valid - wildcards skipped (checked by security_best_practices)
   "Resource": "*"
 }
 ```
@@ -886,10 +1043,10 @@ Ensures Statement IDs are unique within a policy:
 
 ### 6. Wildcard Action Validation
 
-The `security_best_practices_check` handles all wildcard security validation with customizable allowlists:
+The `security_best_practices` handles all wildcard security validation with customizable allowlists:
 
 ```yaml
-security_best_practices_check:
+security_best_practices:
   enabled: true
 
   # Define allowed wildcard patterns (e.g., safe read-only operations)
@@ -922,7 +1079,7 @@ security_best_practices_check:
       - "cloudwatch"
 ```
 
-**Note:** The `action_validation_check` now focuses solely on validating that actions exist in AWS service definitions. All wildcard security concerns are handled by `security_best_practices_check`.
+**Note:** The `action_validation` now focuses solely on validating that actions exist in AWS service definitions. All wildcard security concerns are handled by `security_best_practices`.
 
 ### Configuration Migration
 
@@ -930,7 +1087,7 @@ If you have a custom configuration file from before v1.1.0, update it as follows
 
 **Before (v1.0.x):**
 ```yaml
-action_validation_check:
+action_validation:
   enabled: true
   severity: error
   allowed_wildcards:
@@ -941,13 +1098,13 @@ action_validation_check:
 
 **After (v1.1.0+):**
 ```yaml
-action_validation_check:
+action_validation:
   enabled: true
   severity: error
-  # allowed_wildcards removed - moved to security_best_practices_check
+  # allowed_wildcards removed - moved to security_best_practices
   # disable_wildcard_warnings removed - no longer needed
 
-security_best_practices_check:
+security_best_practices:
   enabled: true
   # Move allowed_wildcards here
   allowed_wildcards:
@@ -1249,8 +1406,18 @@ iam-validator validate --path policy.json --format json --output debug.json
 
 MIT License - see [LICENSE](LICENSE) file for details.
 
+## Future Improvements
+
+See [docs/ROADMAP.md](docs/ROADMAP.md) for planned features and enhancements, including:
+- NotResource support
+- NotAction support
+- Enhanced deny statement validation
+- Policy simulation integration
+- Cross-policy analysis
+
 ## Support
 
 - **Documentation**: This file and `examples/` directory
+- **Roadmap**: [Planned features and improvements](docs/ROADMAP.md)
 - **Issues**: [GitHub Issues](https://github.com/boogy/iam-policy-auditor/issues)
 - **Discussions**: [GitHub Discussions](https://github.com/boogy/iam-policy-auditor/discussions)

{iam_policy_validator-1.2.0 → iam_policy_validator-1.5.0}/Makefile

@@ -8,7 +8,7 @@ help:
 	@echo "  make install          Install production dependencies"
 	@echo "  make dev              Install development dependencies"
 	@echo "  make clean            Clean build artifacts and cache"
-	@echo "  make sync-defaults    Sync defaults.py from default-config.yaml"
+	@echo "  make sync-defaults    [DEPRECATED] Defaults are now in Python modules"
 	@echo ""
 	@echo "Quality:"
 	@echo "  make test             Run tests"
@@ -36,10 +36,16 @@ install:
 dev:
 	uv sync
 
-# Sync defaults.py from YAML config
-sync-defaults: clean
-	@echo "Syncing defaults.py from default-config.yaml..."
-	@uv run python scripts/sync_defaults_from_yaml.py
+# Sync defaults.py from YAML config [DEPRECATED]
+# Defaults are now defined in Python modules at iam_validator/core/data/
+# This target is kept for backward compatibility but is no longer needed
+sync-defaults:
+	@echo "⚠️  DEPRECATED: Defaults are now defined in Python modules"
+	@echo "   Location: iam_validator/core/data/"
+	@echo "   See: docs/modular-configuration.md"
+	@echo ""
+	@echo "   Running legacy sync script for reference..."
+	@uv run python scripts/sync_defaults_from_yaml.py || echo "   (Script may fail - this is expected)"
 
 # Clean
 clean:

{iam_policy_validator-1.2.0 → iam_policy_validator-1.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: iam-policy-validator
-Version: 1.2.0
+Version: 1.5.0
 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://github.com/boogy/iam-policy-validator/tree/main/docs
@@ -448,13 +448,11 @@ settings:
   enable_builtin_checks: true
 
 # Custom check configurations
-security_best_practices_check:
+wildcard_action:
   enabled: true
-  wildcard_action_check:
-    enabled: true
-    severity: high
+  severity: high
 
-action_condition_enforcement_check:
+action_condition_enforcement:
   enabled: true
   severity: critical
   action_condition_requirements:
@@ -465,7 +463,7 @@ action_condition_enforcement_check:
         - condition_key: "iam:PassedToService"
 ```
 
-See [default-config.yaml](default-config.yaml) for a complete configuration example.
+See [examples/configs/full-reference-config.yaml](examples/configs/full-reference-config.yaml) for a complete configuration reference with all available options.
 
 ### GitHub Action Inputs
 
@@ -478,10 +476,11 @@ See [default-config.yaml](default-config.yaml) for a complete configuration exam
 | `recursive`        | Recursively search directories for policy files             | No       | `true`  |
 
 #### GitHub Integration
-| Input           | Description                                | Required | Default |
-| --------------- | ------------------------------------------ | -------- | ------- |
-| `post-comment`  | Post validation results as PR comment      | No       | `true`  |
-| `create-review` | Create line-specific review comments on PR | No       | `true`  |
+| Input            | Description                                               | Required | Default |
+| ---------------- | --------------------------------------------------------- | -------- | ------- |
+| `post-comment`   | Post validation summary as PR conversation comment        | No       | `true`  |
+| `create-review`  | Create line-specific review comments on PR files          | No       | `true`  |
+| `github-summary` | Write summary to GitHub Actions job summary (Actions tab) | No       | `false` |
 
 #### Output Options
 | Input         | Description                                                                      | Required | Default   |
@@ -490,12 +489,12 @@ See [default-config.yaml](default-config.yaml) for a complete configuration exam
 | `output-file` | Path to save output file (for non-console formats)                               | No       | `""`      |
 
 #### AWS Access Analyzer
-| Input                    | Description                                                                 | Required | Default           |
-| ------------------------ | --------------------------------------------------------------------------- | -------- | ----------------- |
-| `use-access-analyzer`    | Use AWS IAM Access Analyzer for validation                                  | No       | `false`           |
-| `access-analyzer-region` | AWS region for Access Analyzer                                              | No       | `us-east-1`       |
-| `policy-type`            | Policy type: `IDENTITY_POLICY`, `RESOURCE_POLICY`, `SERVICE_CONTROL_POLICY` | No       | `IDENTITY_POLICY` |
-| `run-all-checks`         | Run custom checks after Access Analyzer (sequential mode)                   | No       | `false`           |
+| Input                    | Description                                                                                            | Required | Default           |
+| ------------------------ | ------------------------------------------------------------------------------------------------------ | -------- | ----------------- |
+| `use-access-analyzer`    | Use AWS IAM Access Analyzer for validation                                                             | No       | `false`           |
+| `access-analyzer-region` | AWS region for Access Analyzer                                                                         | No       | `us-east-1`       |
+| `policy-type`            | Policy type: `IDENTITY_POLICY`, `RESOURCE_POLICY`, `SERVICE_CONTROL_POLICY`, `RESOURCE_CONTROL_POLICY` | No       | `IDENTITY_POLICY` |
+| `run-all-checks`         | Run custom checks after Access Analyzer (sequential mode)                                              | No       | `false`           |
 
 #### Custom Policy Checks (Access Analyzer)
 | Input                         | Description                                                                 | Required | Default           |
@@ -518,7 +517,7 @@ See [default-config.yaml](default-config.yaml) for a complete configuration exam
 - Configure `aws-services-dir` in your config file for offline validation
 - The action automatically filters IAM policies from mixed JSON/YAML files
 
-See [examples/github-actions/](examples/github-actions/) for 8 ready-to-use workflow examples.
+See [examples/github-actions/](examples/github-actions/) for 9 ready-to-use workflow examples.
 
 ### As a CLI Tool
 
@@ -540,6 +539,12 @@ iam-validator validate --path ./policies/
 # Validate multiple paths
 iam-validator validate --path policy1.json --path ./policies/ --path ./more-policies/
 
+# Validate resource policies (S3 bucket policies, SNS topics, etc.)
+iam-validator validate --path ./bucket-policies/ --policy-type RESOURCE_POLICY
+
+# Validate AWS Organizations Resource Control Policies (RCPs)
+iam-validator validate --path ./rcps/ --policy-type RESOURCE_CONTROL_POLICY
+
 # Generate JSON output
 iam-validator validate --path ./policies/ --format json --output report.json
 
@@ -557,6 +562,106 @@ iam-validator analyze \
   --github-review
 ```
 
+### Policy Type Validation
+
+The validator supports four AWS policy types, each with specific validation rules:
+
+#### 🔷 IDENTITY_POLICY (Default)
+Standard IAM policies attached to users, groups, or roles.
+
+**Requirements:**
+- Should NOT have `Principal` element (implicit - the attached entity)
+- Must have `Action` and `Resource` elements
+
+**Example:**
+```bash
+iam-validator validate --path ./user-policies/ --policy-type IDENTITY_POLICY
+```
+
+#### 🔶 RESOURCE_POLICY
+Policies attached to AWS resources (S3 buckets, SNS topics, KMS keys, etc.).
+
+**Requirements:**
+- MUST have `Principal` element (who can access)
+- Must have `Action`, `Effect`, and `Resource` elements
+- Can use configurable security checks for principal validation
+
+**Example:**
+```bash
+iam-validator validate --path ./bucket-policies/ --policy-type RESOURCE_POLICY
+```
+
+**Advanced Principal Validation:**
+```yaml
+# config.yaml
+principal_validation:
+  enabled: true
+  severity: high
+  # Block public access
+  blocked_principals: ["*"]
+  # Or require specific conditions for public access
+  require_conditions_for:
+    "*":
+      - "aws:SourceArn"
+      - "aws:SourceAccount"
+```
+
+#### 🔷 SERVICE_CONTROL_POLICY
+AWS Organizations SCPs that set permission guardrails.
+
+**Requirements:**
+- Must NOT have `Principal` element (applies to all principals in OU)
+- Typically uses `Deny` effect for guardrails
+- Must have `Action` and `Resource` elements
+
+**Example:**
+```bash
+iam-validator validate --path ./scps/ --policy-type SERVICE_CONTROL_POLICY
+```
+
+#### 🆕 RESOURCE_CONTROL_POLICY
+AWS Organizations RCPs for resource-level access control (released 2024).
+
+**Strict Requirements:**
+- `Effect` MUST be `Deny` (only AWS-managed `RCPFullAWSAccess` can use `Allow`)
+- `Principal` MUST be exactly `"*"` (use `Condition` to restrict)
+- `Action` cannot use `"*"` alone (must be service-specific like `"s3:*"`)
+- Only **5 supported services**: `s3`, `sts`, `sqs`, `secretsmanager`, `kms`
+- `NotAction` and `NotPrincipal` are NOT supported
+- Must have `Resource` or `NotResource` element
+
+**Example:**
+```bash
+iam-validator validate --path ./rcps/ --policy-type RESOURCE_CONTROL_POLICY
+```
+
+**Valid RCP:**
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [{
+    "Sid": "EnforceEncryptionInTransit",
+    "Effect": "Deny",
+    "Principal": "*",
+    "Action": ["s3:*", "sqs:*"],
+    "Resource": "*",
+    "Condition": {
+      "BoolIfExists": {
+        "aws:SecureTransport": "false"
+      }
+    }
+  }]
+}
+```
+
+**What the validator catches:**
+```
+✓ Effect is "Deny" (required for RCPs)
+✓ Principal is "*" (required - restrictions via Condition)
+✓ Actions from supported services (s3, sqs)
+✓ Uses Condition to scope the deny
+```
+
 ### Custom Policy Checks
 
 AWS IAM Access Analyzer provides specialized checks to validate policies against specific security requirements:
@@ -651,7 +756,9 @@ Use as a library in your Python applications:
 
 ```python
 import asyncio
-from iam_validator.core import PolicyLoader, validate_policies, ReportGenerator
+from iam_validator.core.policy_loader import PolicyLoader
+from iam_validator.core.policy_checks import validate_policies
+from iam_validator.core.report import ReportGenerator
 
 async def main():
     # Load policies
@@ -669,6 +776,10 @@ async def main():
 asyncio.run(main())
 ```
 
+**📚 For comprehensive Python library documentation, see:**
+- **[Python Library Usage Guide](docs/python-library-usage.md)** - Complete guide with examples
+- **[Library Examples](examples/library-usage/)** - Runnable code examples
+
 ## Validation Checks
 
 ### 1. Action Validation
@@ -738,6 +849,44 @@ Identifies potential security risks:
 
 ## GitHub Integration Features
 
+### Flexible Comment Options
+
+The validator provides **three independent ways** to display validation results in GitHub:
+
+#### 1. **PR Summary Comment** (`--github-comment`)
+Posts a high-level summary to the PR conversation with:
+- Overall metrics (total policies, issues, severities)
+- Grouped findings by file
+- Detailed issue descriptions with suggestions
+
+#### 2. **Line-Specific Review Comments** (`--github-review`)
+Creates inline review comments on the "Files changed" tab:
+- Comments appear directly on problematic lines
+- Includes rich context (examples, suggestions)
+- Automatically cleaned up on subsequent runs
+- Review status (REQUEST_CHANGES or COMMENT) based on `fail_on_severity` config
+
+#### 3. **GitHub Actions Job Summary** (`--github-summary`)
+Writes a high-level overview to the Actions tab:
+- Visible in workflow run summary
+- Shows key metrics and severity breakdown
+- Clean dashboard view without overwhelming details
+
+**Mix and Match:** Use any combination of these options:
+```bash
+# All three for maximum visibility
+--github-comment --github-review --github-summary
+
+# Only line-specific review comments (clean, minimal)
+--github-review
+
+# Only PR summary comment
+--github-comment
+
+# Only Actions job summary
+--github-summary
+```
+
 ### Smart PR Comment Management
 
 The validator intelligently manages PR comments to keep your PRs clean:
@@ -751,8 +900,9 @@ The validator intelligently manages PR comments to keep your PRs clean:
 **Behavior:**
 - ✅ **No Duplicates**: Summary comments are updated, not duplicated
 - ✅ **Clean PR**: Old review comments automatically deleted before new validation
-- ✅ **Identifiable**: All bot comments tagged with `🤖 IAM Policy Validator`
+- ✅ **Identifiable**: All bot comments use HTML identifiers (invisible to users)
 - ✅ **Progressive**: In streaming mode, comments appear file-by-file
+- ✅ **Smart Review Status**: Uses `fail_on_severity` config to determine REQUEST_CHANGES vs COMMENT
 
 **Example:**
 ```
@@ -824,6 +974,7 @@ The comprehensive [DOCS.md](DOCS.md) file contains everything you need:
   - [Custom Checks](examples/custom_checks/)
   - [Configuration Files](examples/configs/)
   - [Test IAM Policies](examples/iam-test-policies/)
+- **[Roadmap](docs/ROADMAP.md)** - Planned features and improvements
 - **[AWS Services Backup Guide](docs/aws-services-backup.md)** - Offline validation
 - **[Contributing Guide](CONTRIBUTING.md)** - Contribution guidelines
 - **[Publishing Guide](docs/development/PUBLISHING.md)** - Release process