clean up excessive comments across all modules

Author: bertrandmbanwi

src/infraguard/cli.py

@@ -14,13 +14,11 @@
     pretty_exceptions_enable=False,
 )
 
-
 def version_callback(value: bool) -> None:
     if value:
         typer.echo(f"infraguard {__version__}")
         raise typer.Exit()
 
-
 @app.callback()
 def main(
     version: bool = typer.Option(
@@ -34,8 +32,6 @@ def main(
 ) -> None:
     """Infrastructure guardrails for teams that ship fast."""
 
-
-# Register subcommands — imported here to avoid circular deps
 from infraguard.iam_check.command import app as iam_check_app  # noqa: E402
 from infraguard.plan_risk.command import app as plan_risk_app  # noqa: E402
 from infraguard.tag_audit.command import app as tag_audit_app  # noqa: E402

src/infraguard/common/config.py

@@ -14,7 +14,6 @@ def load_rules(path: Path) -> dict[str, Any]:
         data = yaml.safe_load(f)
     return data if data else {}
 
-
 def merge_rules(defaults: dict[str, Any], overrides: dict[str, Any]) -> dict[str, Any]:
     """Deep-merge overrides into defaults. Lists are replaced, dicts are merged."""
     merged = defaults.copy()

src/infraguard/common/models.py

@@ -37,7 +37,6 @@ def to_dict(self) -> dict[str, Any]:
             "metadata": self.metadata,
         }
 
-
 @dataclass
 class RiskChange:
     """A scored resource change from a Terraform plan."""
@@ -63,7 +62,6 @@ def to_dict(self) -> dict[str, Any]:
             "detail": self.detail,
         }
 
-
 @dataclass
 class Report:
     """Aggregated results from an infraguard analysis."""

src/infraguard/common/reporter.py

@@ -16,10 +16,6 @@
 
 console = Console(stderr=True)
 
-
-# ── Table (Rich) ──────────────────────────────────────────────
-
-
 def render_plan_risk_table(report: Report, threshold: int | None = None) -> None:
     """Print a Rich-formatted plan risk report to stderr."""
     console.print()
@@ -79,7 +75,6 @@ def render_plan_risk_table(report: Report, threshold: int | None = None) -> None
             )
     console.print()
 
-
 def render_findings_table(report: Report, title: str, threshold_info: str = "") -> None:
     """Print a Rich-formatted findings report to stderr."""
     console.print()
@@ -119,18 +114,10 @@ def render_findings_table(report: Report, title: str, threshold_info: str = "")
         console.print(f"  {threshold_info}")
     console.print()
 
-
-# ── JSON ──────────────────────────────────────────────────────
-
-
 def render_json(report: Report) -> None:
     """Print JSON report to stdout."""
     sys.stdout.write(report.to_json() + "\n")
 
-
-# ── Markdown ──────────────────────────────────────────────────
-
-
 def render_plan_risk_markdown(report: Report, threshold: int | None = None) -> None:
     """Print markdown-formatted plan risk report to stdout."""
     lines = ["## Terraform Plan Risk Report", ""]
@@ -162,7 +149,6 @@ def render_plan_risk_markdown(report: Report, threshold: int | None = None) -> N
 
     sys.stdout.write("\n".join(lines) + "\n")
 
-
 def render_findings_markdown(report: Report, title: str) -> None:
     """Print markdown-formatted findings report to stdout."""
     lines = [f"## {title}", ""]
@@ -186,10 +172,6 @@ def render_findings_markdown(report: Report, title: str) -> None:
 
     sys.stdout.write("\n".join(lines) + "\n")
 
-
-# ── SARIF ─────────────────────────────────────────────────────
-
-
 def render_sarif(report: Report) -> None:
     """Print SARIF 2.1.0 report to stdout for GitHub Code Scanning integration."""
     sarif: dict[str, Any] = {
@@ -248,10 +230,6 @@ def render_sarif(report: Report) -> None:
 
     sys.stdout.write(json.dumps(sarif, indent=2) + "\n")
 
-
-# ── Helpers ───────────────────────────────────────────────────
-
-
 def _severity_emoji(severity: Severity) -> str:
     return {
         Severity.CRITICAL: ":red_circle:",
@@ -261,7 +239,6 @@ def _severity_emoji(severity: Severity) -> str:
         Severity.INFO: ":white_circle:",
     }[severity]
 
-
 def _sarif_level(severity: Severity) -> str:
     if severity >= Severity.HIGH:
         return "error"

src/infraguard/common/severity.py

@@ -26,7 +26,6 @@ def color(self) -> str:
     def icon(self) -> str:
         return _ICONS[self]
 
-
 _COLORS: dict[Severity, str] = {
     Severity.INFO: "dim",
     Severity.LOW: "cyan",

src/infraguard/iam_check/analyzer.py

@@ -18,7 +18,6 @@
     check_wildcard_resources,
 )
 
-# All checks to run against each statement
 ALL_CHECKS = [
     check_admin_access,
     check_wildcard_actions,
@@ -28,7 +27,6 @@
     check_cross_account_access,
 ]
 
-
 def analyze_policy_file(path: Path) -> Report:
     """Analyze a single IAM policy JSON file.
 
@@ -52,12 +50,10 @@ def analyze_policy_file(path: Path) -> Report:
             f"or 'policies' key in {path}"
         )
 
-
 def analyze_policy_document(document: dict[str, Any], policy_name: str = "inline") -> Report:
     """Analyze a single IAM policy document dict."""
     return _analyze_single(document, policy_name)
 
-
 def analyze_aws_role(
     role_name: str, profile: str | None = None, region: str = "us-east-1"
 ) -> Report:
@@ -75,7 +71,6 @@ def analyze_aws_role(
 
     policies: list[dict[str, Any]] = []
 
-    # Inline policies
     inline_names = iam.list_role_policies(RoleName=role_name)["PolicyNames"]
     for name in inline_names:
         resp = iam.get_role_policy(RoleName=role_name, PolicyName=name)
@@ -84,7 +79,6 @@ def analyze_aws_role(
             doc = json.loads(unquote(doc))
         policies.append({"name": f"{role_name}/{name} (inline)", "document": doc})
 
-    # Attached managed policies
     attached = iam.list_attached_role_policies(RoleName=role_name)["AttachedPolicies"]
     for policy in attached:
         arn = policy["PolicyArn"]
@@ -98,7 +92,6 @@ def analyze_aws_role(
 
     return _analyze_multiple(policies)
 
-
 def _analyze_single(document: dict[str, Any], policy_name: str) -> Report:
     """Run all checks against a single policy document."""
     findings: list[Finding] = []
@@ -111,7 +104,6 @@ def _analyze_single(document: dict[str, Any], policy_name: str) -> Report:
         for check_fn in ALL_CHECKS:
             findings.extend(check_fn(stmt, i, policy_name))
 
-    # Deduplicate — same title + resource = same finding
     seen = set()
     unique_findings = []
     for f in findings:
@@ -123,7 +115,6 @@ def _analyze_single(document: dict[str, Any], policy_name: str) -> Report:
     summary = _build_summary(unique_findings, [policy_name])
     return Report(module="iam-check", findings=unique_findings, summary=summary)
 
-
 def _analyze_multiple(policies: list[dict[str, Any]]) -> Report:
     """Run checks across multiple policy documents."""
     all_findings: list[Finding] = []
@@ -140,7 +131,6 @@ def _analyze_multiple(policies: list[dict[str, Any]]) -> Report:
     summary = _build_summary(all_findings, policy_names)
     return Report(module="iam-check", findings=all_findings, summary=summary)
 
-
 def _build_summary(findings: list[Finding], policy_names: list[str]) -> dict[str, Any]:
     """Build summary statistics for an IAM check report."""
     counts: dict[str, int] = {s.label: 0 for s in Severity}

src/infraguard/iam_check/checks.py

@@ -37,7 +37,6 @@ def check_admin_access(
         )
     return findings
 
-
 def check_wildcard_actions(
     statement: dict[str, Any], stmt_index: int, policy_name: str
 ) -> list[Finding]:
@@ -51,7 +50,7 @@ def check_wildcard_actions(
 
     for action in actions:
         if action == "*":
-            continue  # Handled by admin_access check
+            continue
 
         if action.endswith(":*"):
             service = action.split(":")[0]
@@ -77,7 +76,6 @@ def check_wildcard_actions(
             )
     return findings
 
-
 def check_wildcard_resources(
     statement: dict[str, Any], stmt_index: int, policy_name: str
 ) -> list[Finding]:
@@ -93,11 +91,9 @@ def check_wildcard_resources(
     if "*" not in resources:
         return findings
 
-    # Skip if already flagged as full admin
     if "*" in actions:
         return findings
 
-    # Check if any action is on a sensitive service
     has_sensitive = any(
         any(a.startswith(prefix) for prefix in SENSITIVE_SERVICE_PREFIXES)
         for a in actions
@@ -116,7 +112,6 @@ def check_wildcard_resources(
     )
     return findings
 
-
 def check_dangerous_actions(
     statement: dict[str, Any], stmt_index: int, policy_name: str
 ) -> list[Finding]:
@@ -142,7 +137,6 @@ def check_dangerous_actions(
             )
     return findings
 
-
 def check_missing_conditions(
     statement: dict[str, Any], stmt_index: int, policy_name: str
 ) -> list[Finding]:
@@ -156,7 +150,7 @@ def check_missing_conditions(
         return findings
 
     if conditions:
-        return findings  # Conditions present, skip
+        return findings
 
     sensitive_actions = [
         a for a in actions
@@ -175,7 +169,6 @@ def check_missing_conditions(
         )
     return findings
 
-
 def check_cross_account_access(
     statement: dict[str, Any], stmt_index: int, policy_name: str
 ) -> list[Finding]:
@@ -191,7 +184,6 @@ def check_cross_account_access(
     if not principal:
         return findings
 
-    # Check for cross-account principals
     aws_principals = []
     if isinstance(principal, str):
         if principal == "*":
@@ -217,10 +209,6 @@ def check_cross_account_access(
         )
     return findings
 
-
-# ── Helpers ───────────────────────────────────────────────────
-
-
 def _normalize_list(value: Any) -> list[str]:
     """Ensure a value is a list of strings (IAM allows string or list)."""
     if isinstance(value, str):

src/infraguard/iam_check/command.py

@@ -18,7 +18,6 @@
 app = typer.Typer(no_args_is_help=True)
 console = Console(stderr=True)
 
-
 def _parse_max_findings(value: str) -> dict[str, int]:
     """Parse max-findings threshold string like 'critical:0,high:3'."""
     result = {}
@@ -28,7 +27,6 @@ def _parse_max_findings(value: str) -> dict[str, int]:
             result[parts[0].strip().upper()] = int(parts[1].strip())
     return result
 
-
 @app.callback(invoke_without_command=True)
 def iam_check(
     file: Path | None = typer.Option(

src/infraguard/iam_check/rules.py

@@ -4,11 +4,7 @@
 
 from infraguard.common.severity import Severity
 
-# ── Dangerous actions ─────────────────────────────────────────
-# Actions that grant significant control and should be flagged.
-
 DANGEROUS_ACTIONS: dict[str, Severity] = {
-    # IAM — identity escalation
     "iam:CreateUser": Severity.HIGH,
     "iam:CreateRole": Severity.HIGH,
     "iam:AttachUserPolicy": Severity.CRITICAL,
@@ -24,57 +20,45 @@
     "iam:CreatePolicyVersion": Severity.HIGH,
     "iam:SetDefaultPolicyVersion": Severity.HIGH,
 
-    # STS — credential abuse
     "sts:AssumeRole": Severity.MEDIUM,
     "sts:AssumeRoleWithSAML": Severity.MEDIUM,
     "sts:AssumeRoleWithWebIdentity": Severity.MEDIUM,
     "sts:GetFederationToken": Severity.MEDIUM,
 
-    # S3 — data destruction
     "s3:DeleteBucket": Severity.HIGH,
     "s3:PutBucketPolicy": Severity.HIGH,
     "s3:PutBucketAcl": Severity.HIGH,
 
-    # EC2 — infrastructure destruction
     "ec2:TerminateInstances": Severity.HIGH,
     "ec2:DeleteSecurityGroup": Severity.MEDIUM,
     "ec2:AuthorizeSecurityGroupIngress": Severity.MEDIUM,
     "ec2:ModifyInstanceAttribute": Severity.MEDIUM,
 
-    # RDS — data destruction
     "rds:DeleteDBInstance": Severity.HIGH,
     "rds:DeleteDBCluster": Severity.HIGH,
     "rds:ModifyDBInstance": Severity.MEDIUM,
 
-    # Lambda — code execution
     "lambda:CreateFunction": Severity.MEDIUM,
     "lambda:UpdateFunctionCode": Severity.HIGH,
     "lambda:AddPermission": Severity.HIGH,
     "lambda:CreateEventSourceMapping": Severity.MEDIUM,
 
-    # KMS — encryption control
     "kms:Decrypt": Severity.MEDIUM,
     "kms:ScheduleKeyDeletion": Severity.CRITICAL,
     "kms:DisableKey": Severity.HIGH,
     "kms:PutKeyPolicy": Severity.CRITICAL,
 
-    # Organizations — org-level control
     "organizations:LeaveOrganization": Severity.CRITICAL,
     "organizations:DeleteOrganization": Severity.CRITICAL,
 
-    # CloudTrail — audit evasion
     "cloudtrail:DeleteTrail": Severity.CRITICAL,
     "cloudtrail:StopLogging": Severity.CRITICAL,
     "cloudtrail:UpdateTrail": Severity.HIGH,
 
-    # GuardDuty — security evasion
     "guardduty:DeleteDetector": Severity.CRITICAL,
     "guardduty:DisassociateFromMasterAccount": Severity.HIGH,
 }
 
-# ── Sensitive action prefixes ─────────────────────────────────
-# Actions on these services with broad wildcards are extra risky.
-
 SENSITIVE_SERVICE_PREFIXES: list[str] = [
     "iam:",
     "sts:",
@@ -87,8 +71,6 @@
     "access-analyzer:",
 ]
 
-# ── Suggested replacements for common overpermissions ─────────
-
 WILDCARD_SUGGESTIONS: dict[str, list[str]] = {
     "s3:*": ["s3:GetObject", "s3:PutObject", "s3:ListBucket", "s3:GetBucketLocation"],
     "ec2:*": ["ec2:DescribeInstances", "ec2:DescribeSecurityGroups", "ec2:DescribeVpcs"],

src/infraguard/plan_risk/command.py

@@ -17,7 +17,6 @@
 
 app = typer.Typer(no_args_is_help=False)
 
-
 @app.callback(invoke_without_command=True)
 def plan_risk(
     file: Path | None = typer.Option(