iam-policy-validator 1.3.0__tar.gz → 1.4.0__tar.gz

{iam_policy_validator-1.3.0 → iam_policy_validator-1.4.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,6 +722,112 @@ 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.

{iam_policy_validator-1.3.0 → iam_policy_validator-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: iam-policy-validator
-Version: 1.3.0
+Version: 1.4.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
@@ -478,10 +478,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   |
@@ -494,7 +495,7 @@ See [default-config.yaml](default-config.yaml) for a complete configuration exam
 | ------------------------ | --------------------------------------------------------------------------- | -------- | ----------------- |
 | `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` |
+| `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)
@@ -540,6 +541,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 +564,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_check:
+  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 +758,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 +778,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 +851,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 +902,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:**
 ```

{iam_policy_validator-1.3.0 → iam_policy_validator-1.4.0}/README.md

@@ -436,10 +436,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   |
@@ -452,7 +453,7 @@ See [default-config.yaml](default-config.yaml) for a complete configuration exam
 | ------------------------ | --------------------------------------------------------------------------- | -------- | ----------------- |
 | `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` |
+| `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)
@@ -498,6 +499,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
 
@@ -515,6 +522,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_check:
+  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:
@@ -609,7 +716,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
@@ -627,6 +736,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
@@ -696,6 +809,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:
@@ -709,8 +860,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:**
 ```

{iam_policy_validator-1.3.0 → iam_policy_validator-1.4.0}/aws_services/_manifest.json

@@ -1,5 +1,5 @@
 {
-  "download_date": "2025-10-29T23:23:11.519006+00:00",
+  "download_date": "2025-10-31T23:41:25.480606+00:00",
   "total_services": 430,
   "successful_downloads": 430,
   "failed_downloads": 0,