plugin-scanner 2.0.1096__tar.gz → 2.0.1097__tar.gz

{plugin_scanner-2.0.1096 → plugin_scanner-2.0.1097}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plugin-scanner
-Version: 2.0.1096
+Version: 2.0.1097
 Summary: Lint, verify, and gate plugin ecosystems for maintainers, CI, and publish workflows.
 Project-URL: Homepage, https://hol.org/guard
 Project-URL: Documentation, https://github.com/hashgraph-online/hol-guard/tree/main/docs/guard

{plugin_scanner-2.0.1096 → plugin_scanner-2.0.1097}/docs/guard/architecture.md

@@ -55,3 +55,4 @@ Cisco AIBOM stays out of Guard runtime policy in this phase. If it returns later
 - [Storage command extension coverage](command-storage-extension-coverage.md)
 - [Backup command extension coverage](command-backup-extension-coverage.md)
 - [Remote command extension coverage](command-remote-extension-coverage.md)
+- [Database command extension coverage](command-database-extension-coverage.md)

plugin_scanner-2.0.1097/docs/guard/command-database-extension-coverage.md

@@ -0,0 +1,25 @@
+# Database Command Extension Coverage
+
+Guard's built-in database extensions match parsed executables, leading options, exact subcommands, flags, and bounded argument positions. They do not scan quoted documentation or arbitrary shell text for database keywords.
+
+## Covered Operations
+
+- PostgreSQL database removal through `dropdb`
+- MySQL database removal in `mysqladmin` multi-command sequences and documented abbreviations
+- MongoDB collection replacement through `mongorestore --drop`
+- Redis `FLUSHALL`, `FLUSHDB`, `DEL`, and `UNLINK`
+- SQLite `.restore` command arguments with a backup payload
+- Supabase database reset and migration rollback through direct and package-runner launch forms
+- Portable `.cmd` and `.exe` launcher names
+- MongoDB documented dry-run variants
+
+Free-form SQL passed to interactive clients is intentionally deferred until Guard has a bounded, dialect-aware statement matcher.
+
+## References
+
+- [PostgreSQL dropdb](https://www.postgresql.org/docs/current/app-dropdb.html)
+- [MySQL mysqladmin](https://dev.mysql.com/doc/refman/8.4/en/mysqladmin.html)
+- [MongoDB mongorestore](https://www.mongodb.com/docs/database-tools/mongorestore/)
+- [Redis commands](https://redis.io/docs/latest/commands/)
+- [SQLite command-line shell](https://www.sqlite.org/cli.html)
+- [Supabase database reset](https://supabase.com/docs/reference/cli/supabase-db-reset)

{plugin_scanner-2.0.1096 → plugin_scanner-2.0.1097}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "plugin-scanner"
-version = "2.0.1096"
+version = "2.0.1097"
 description = "Lint, verify, and gate plugin ecosystems for maintainers, CI, and publish workflows."
 readme = "README.md"
 license = "Apache-2.0"

{plugin_scanner-2.0.1096 → plugin_scanner-2.0.1097}/pyproject.toml.bak

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hol-guard"
-version = "2.0.1096"
+version = "2.0.1097"
 description = "Open-source antivirus and runtime protection for AI agents, tools, MCP servers, plugins, skills, and package installs."
 readme = "README.md"
 license = "Apache-2.0"

{plugin_scanner-2.0.1096 → plugin_scanner-2.0.1097}/src/codex_plugin_scanner/guard/runtime/command_builtin_extension_catalog.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 from .command_backup_extensions import BACKUP_COMMAND_EXTENSION_SPECS, BACKUP_COMMAND_RULES
 from .command_cloud_extensions import CLOUD_COMMAND_EXTENSION_SPECS, CLOUD_COMMAND_RULES
+from .command_database_extensions import DATABASE_COMMAND_EXTENSION_SPECS, DATABASE_COMMAND_RULES
 from .command_domain_extensions import DOMAIN_COMMAND_EXTENSION_SPECS, DOMAIN_COMMAND_RULES
 from .command_extension_specs import CommandExtensionValues, command_extension_values
 from .command_remote_extensions import REMOTE_COMMAND_EXTENSION_SPECS, REMOTE_COMMAND_RULES
@@ -12,6 +13,7 @@ from .command_storage_extensions import STORAGE_COMMAND_EXTENSION_SPECS, STORAGE
 _DIRECT_EXTENSION_CATALOGS = (
     (DOMAIN_COMMAND_EXTENSION_SPECS, DOMAIN_COMMAND_RULES),
     (CLOUD_COMMAND_EXTENSION_SPECS, CLOUD_COMMAND_RULES),
+    (DATABASE_COMMAND_EXTENSION_SPECS, DATABASE_COMMAND_RULES),
     (STORAGE_COMMAND_EXTENSION_SPECS, STORAGE_COMMAND_RULES),
     (BACKUP_COMMAND_EXTENSION_SPECS, BACKUP_COMMAND_RULES),
     (REMOTE_COMMAND_EXTENSION_SPECS, REMOTE_COMMAND_RULES),

{plugin_scanner-2.0.1096 → plugin_scanner-2.0.1097}/src/codex_plugin_scanner/guard/runtime/command_builtin_rules.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 from .command_backup_extensions import BACKUP_COMMAND_RULES
 from .command_cloud_extensions import CLOUD_COMMAND_RULES
+from .command_database_extensions import DATABASE_COMMAND_RULES
 from .command_domain_extensions import DOMAIN_COMMAND_RULES
 from .command_remote_extensions import REMOTE_COMMAND_RULES
 from .command_rules import (
@@ -55,6 +56,12 @@ COMMAND_ACTION_RISK_CLASSES: dict[str, tuple[str, ...]] = {
     "ssh configured execution command": ("execution", "network_egress"),
     "scp overwrite command": ("destructive_shell", "network_egress"),
     "rsync destructive command": ("destructive_shell", "network_egress"),
+    "postgresql destructive command": ("destructive_shell", "network_egress"),
+    "mysql destructive command": ("destructive_shell", "network_egress"),
+    "mongodb destructive command": ("destructive_shell", "network_egress"),
+    "redis destructive command": ("destructive_shell", "network_egress"),
+    "sqlite destructive command": ("destructive_shell",),
+    "supabase destructive command": ("destructive_shell", "network_egress"),
     "rsync remote shell command": ("execution", "network_egress"),
 }
 _GIT_GLOBAL_OPTIONS_WITH_VALUES = frozenset(
@@ -350,6 +357,7 @@ BUILT_IN_COMMAND_RULES = (
     *STORAGE_COMMAND_RULES,
     *BACKUP_COMMAND_RULES,
     *REMOTE_COMMAND_RULES,
+    *DATABASE_COMMAND_RULES,
 )
 
 _RULES_BY_EXTENSION: dict[str, tuple[CommandSafetyRule, ...]] = {}

plugin_scanner-2.0.1097/src/codex_plugin_scanner/guard/runtime/command_database_extensions.py

@@ -0,0 +1,349 @@
+"""Structured rules and metadata for database administration commands."""
+
+from __future__ import annotations
+
+from .command_database_matchers import ArgumentCommandMatcher, CommandSequenceMatcher, LeadingSubcommandMatcher
+from .command_extension_matchers import executable_matcher, executable_names, safe_flag_variant
+from .command_extension_specs import CommandExtensionSpec
+from .command_rules import (
+    AnyMatcher,
+    CommandMatcher,
+    CommandSafetyRule,
+    CommandSafeVariant,
+    ExecutableMatcher,
+)
+from .command_structured_matchers import LeadingOperandCountMatcher
+
+_POSTGRES_OPTIONS_WITH_VALUES = frozenset({"-h", "-p", "-U", "--host", "--maintenance-db", "--port", "--username"})
+_MYSQL_GLOBAL_OPTIONS = frozenset(
+    {
+        "-h",
+        "--host",
+        "-P",
+        "--port",
+        "-S",
+        "--socket",
+        "-u",
+        "--user",
+        "--defaults-file",
+        "--defaults-extra-file",
+        "--bind-address",
+        "--character-sets-dir",
+        "--compression-algorithms",
+        "--connect-timeout",
+        "--count",
+        "--default-auth",
+        "--login-path",
+        "--max-allowed-packet",
+        "--plugin-dir",
+        "--protocol",
+        "--server-public-key-path",
+        "--shared-memory-base-name",
+        "--shutdown-timeout",
+        "--sleep",
+        "--ssl-ca",
+        "--ssl-capath",
+        "--ssl-cert",
+        "--ssl-cipher",
+        "--ssl-crl",
+        "--ssl-crlpath",
+        "--ssl-key",
+        "--tls-ciphersuites",
+        "--tls-sni-servername",
+        "--tls-version",
+        "--zstd-compression-level",
+        "-i",
+    }
+)
+_REDIS_GLOBAL_OPTIONS = frozenset(
+    {
+        "-a",
+        "-d",
+        "-D",
+        "-h",
+        "-i",
+        "-n",
+        "-p",
+        "-r",
+        "-s",
+        "-t",
+        "-u",
+        "-X",
+        "--cacert",
+        "--cacertdir",
+        "--cert",
+        "--eval",
+        "--key",
+        "--pass",
+        "--sni",
+        "--show-pushes",
+        "--user",
+    }
+)
+_SUPABASE_GLOBAL_OPTIONS = frozenset(
+    {"--agent", "--dns-resolver", "--network-id", "--output", "--profile", "--workdir", "-o"}
+)
+_SUPABASE_GLOBAL_FLAGS = frozenset({"--create-ticket", "--debug", "--experimental", "--yes"})
+_SUPABASE_FORBIDDEN_FLAGS = frozenset({"--help", "--version", "-h", "-v"})
+_RUNNER_OPTIONS_WITH_VALUES = frozenset(
+    {"--cache", "--call", "--dir", "--filter", "--package", "--reporter", "--workspace", "-C", "-F", "-c", "-p", "-w"}
+)
+_RUNNER_FLAGS = frozenset(
+    {"--aggregate-output", "--silent", "--stream", "--use-stderr", "--workspace-root", "--yes", "-y"}
+)
+_POSTGRES_DROP = LeadingOperandCountMatcher(
+    executables=executable_names("dropdb"),
+    minimum_operands=1,
+    options_with_values=_POSTGRES_OPTIONS_WITH_VALUES,
+    forbidden_flags=frozenset({"--help", "--version", "-?", "-V"}),
+)
+_MYSQL_DROP = CommandSequenceMatcher(
+    executables=executable_names("mysqladmin"),
+    command_arities=(
+        ("create", 1),
+        ("debug", 0),
+        ("drop", 1),
+        ("extended-status", 0),
+        ("flush-hosts", 0),
+        ("flush-logs", 0),
+        ("flush-privileges", 0),
+        ("flush-status", 0),
+        ("kill", 1),
+        ("password", 1),
+        ("ping", 0),
+        ("processlist", 0),
+        ("reload", 0),
+        ("refresh", 0),
+        ("shutdown", 0),
+        ("start-replica", 0),
+        ("start-slave", 0),
+        ("status", 0),
+        ("stop-replica", 0),
+        ("stop-slave", 0),
+        ("variables", 0),
+        ("version", 0),
+    ),
+    target_commands=frozenset({"drop"}),
+    options_with_values=_MYSQL_GLOBAL_OPTIONS,
+    forbidden_flags=frozenset({"--help", "--version", "-?", "-V"}),
+)
+_MONGO_RESTORE_DROP = AnyMatcher(
+    matchers=(
+        executable_matcher(
+            "mongorestore",
+            required_flags=frozenset({"--drop"}),
+            forbidden_flags=frozenset({"--help", "--version"}),
+        ),
+    )
+)
+_REDIS_MUTATION = AnyMatcher(
+    matchers=tuple(
+        LeadingSubcommandMatcher(
+            executables=executable_names("redis-cli"),
+            subcommands=(command,),
+            options_with_values=_REDIS_GLOBAL_OPTIONS,
+            forbidden_flags=frozenset({"--eval", "--help", "--version", "-?"}),
+        )
+        for command in ("flushall", "flushdb", "del", "unlink")
+    )
+)
+_SQLITE_RESTORE = ArgumentCommandMatcher(
+    executables=executable_names("sqlite3"),
+    command=".restore",
+    minimum_abbreviation_length=len(".rest"),
+    minimum_position=1,
+)
+
+
+def _supabase_matchers(*subcommands: str) -> tuple[ExecutableMatcher, ...]:
+    interspersed_options = _SUPABASE_GLOBAL_OPTIONS | _RUNNER_OPTIONS_WITH_VALUES
+    interspersed_flags = _SUPABASE_GLOBAL_FLAGS | _RUNNER_FLAGS
+    return (
+        ExecutableMatcher(
+            executables=executable_names("supabase"),
+            subcommands=subcommands,
+            forbidden_flags=_SUPABASE_FORBIDDEN_FLAGS,
+            interspersed_options_with_values=_SUPABASE_GLOBAL_OPTIONS,
+            interspersed_flags=_SUPABASE_GLOBAL_FLAGS,
+        ),
+        ExecutableMatcher(
+            executables=executable_names("npx") | executable_names("bunx"),
+            subcommands=("supabase", *subcommands),
+            forbidden_flags=_SUPABASE_FORBIDDEN_FLAGS,
+            interspersed_options_with_values=interspersed_options,
+            interspersed_flags=interspersed_flags,
+        ),
+        ExecutableMatcher(
+            executables=executable_names("pnpm") | executable_names("yarn"),
+            subcommands=("supabase", *subcommands),
+            forbidden_flags=_SUPABASE_FORBIDDEN_FLAGS,
+            interspersed_options_with_values=interspersed_options,
+            interspersed_flags=interspersed_flags,
+        ),
+        ExecutableMatcher(
+            executables=executable_names("npm") | executable_names("pnpm"),
+            subcommands=("exec", "supabase", *subcommands),
+            forbidden_flags=_SUPABASE_FORBIDDEN_FLAGS,
+            interspersed_options_with_values=interspersed_options,
+            interspersed_flags=interspersed_flags,
+        ),
+        ExecutableMatcher(
+            executables=executable_names("pnpm") | executable_names("yarn"),
+            subcommands=("dlx", "supabase", *subcommands),
+            forbidden_flags=_SUPABASE_FORBIDDEN_FLAGS,
+            interspersed_options_with_values=interspersed_options,
+            interspersed_flags=interspersed_flags,
+        ),
+    )
+
+
+_SUPABASE_RESET = AnyMatcher(matchers=_supabase_matchers("db", "reset"))
+_SUPABASE_MUTATION = AnyMatcher(
+    matchers=(
+        *_SUPABASE_RESET.matchers,
+        *_supabase_matchers("migration", "down"),
+    )
+)
+
+
+def _database_rule(
+    *,
+    rule_id: str,
+    title: str,
+    description: str,
+    matcher: CommandMatcher,
+    action_class: str,
+    safer_alternative: str,
+    risk_classes: tuple[str, ...] = ("destructive_shell", "network_egress"),
+    safe_variants: tuple[CommandSafeVariant, ...] = (),
+) -> CommandSafetyRule:
+    return CommandSafetyRule(
+        rule_id=rule_id,
+        title=title,
+        description=description,
+        severity="critical",
+        risk_classes=risk_classes,
+        action_classes=(action_class,),
+        safer_alternatives=(safer_alternative,),
+        matcher=matcher,
+        safe_variants=safe_variants,
+    )
+
+
+DATABASE_COMMAND_RULES = (
+    _database_rule(
+        rule_id="command.database.postgresql.drop",
+        title="PostgreSQL database removal",
+        description="Identifies dropdb invocations that remove a PostgreSQL database.",
+        matcher=_POSTGRES_DROP,
+        action_class="PostgreSQL destructive command",
+        safer_alternative="List the target database, active connections, and a current backup before removal.",
+    ),
+    _database_rule(
+        rule_id="command.database.mysql.drop",
+        title="MySQL database removal",
+        description="Identifies mysqladmin drop operations that remove a database and its tables.",
+        matcher=_MYSQL_DROP,
+        action_class="MySQL destructive command",
+        safer_alternative="List the target schema and verify a current backup before removal.",
+    ),
+    _database_rule(
+        rule_id="command.database.mongodb.restore-drop",
+        title="MongoDB destructive restore",
+        description="Identifies mongorestore --drop operations that replace target collections.",
+        matcher=_MONGO_RESTORE_DROP,
+        action_class="MongoDB destructive command",
+        safer_alternative="Run mongorestore with --dryRun and inspect the selected database collections first.",
+        safe_variants=(
+            safe_flag_variant(
+                _MONGO_RESTORE_DROP,
+                variant_id="dry-run",
+                title="MongoDB restore dry run",
+                flag="--dryRun",
+            ),
+        ),
+    ),
+    _database_rule(
+        rule_id="command.database.redis.delete",
+        title="Redis key deletion",
+        description="Identifies Redis commands that delete keys from one or every database.",
+        matcher=_REDIS_MUTATION,
+        action_class="Redis destructive command",
+        safer_alternative="Inspect the selected database and exact keys before deleting them.",
+    ),
+    _database_rule(
+        rule_id="command.database.sqlite.restore",
+        title="SQLite database restore",
+        description="Identifies SQLite .restore operations that replace database content from a backup.",
+        matcher=_SQLITE_RESTORE,
+        action_class="SQLite destructive command",
+        safer_alternative="Restore into a new database file and compare its contents before replacement.",
+        risk_classes=("destructive_shell",),
+    ),
+    _database_rule(
+        rule_id="command.database.supabase.reset",
+        title="Supabase database reset",
+        description="Identifies Supabase reset and migration-down operations that discard database state.",
+        matcher=_SUPABASE_MUTATION,
+        action_class="Supabase destructive command",
+        safer_alternative="Confirm the target and create a database dump before resetting or rolling back migrations.",
+    ),
+)
+
+
+DATABASE_COMMAND_EXTENSION_SPECS = (
+    CommandExtensionSpec(
+        extension_id="command.database.postgresql",
+        name="PostgreSQL command protection",
+        description="Reviews explicit PostgreSQL database removal commands.",
+        action_classes=("PostgreSQL destructive command",),
+        risk_classes=("destructive_shell", "network_egress"),
+        safer_alternatives=("Verify active connections and a current backup before running dropdb.",),
+        reference_urls=("https://www.postgresql.org/docs/current/app-dropdb.html",),
+    ),
+    CommandExtensionSpec(
+        extension_id="command.database.mysql",
+        name="MySQL command protection",
+        description="Reviews mysqladmin database removal operations.",
+        action_classes=("MySQL destructive command",),
+        risk_classes=("destructive_shell", "network_egress"),
+        safer_alternatives=("Inspect the target schema and backup state before removal.",),
+        reference_urls=("https://dev.mysql.com/doc/refman/8.4/en/mysqladmin.html",),
+    ),
+    CommandExtensionSpec(
+        extension_id="command.database.mongodb",
+        name="MongoDB command protection",
+        description="Reviews restore operations that drop and replace collections.",
+        action_classes=("MongoDB destructive command",),
+        risk_classes=("destructive_shell", "network_egress"),
+        safer_alternatives=("Use mongorestore --dryRun and inspect selected database collections first.",),
+        reference_urls=("https://www.mongodb.com/docs/database-tools/mongorestore/",),
+    ),
+    CommandExtensionSpec(
+        extension_id="command.database.redis",
+        name="Redis command protection",
+        description="Reviews Redis key deletion and database flush commands.",
+        action_classes=("Redis destructive command",),
+        risk_classes=("destructive_shell", "network_egress"),
+        safer_alternatives=("Inspect the selected database and exact key set before deletion.",),
+        reference_urls=("https://redis.io/docs/latest/commands/",),
+    ),
+    CommandExtensionSpec(
+        extension_id="command.database.sqlite",
+        name="SQLite command protection",
+        description="Reviews SQLite restore operations that replace database content.",
+        action_classes=("SQLite destructive command",),
+        risk_classes=("destructive_shell",),
+        safer_alternatives=("Restore into a new database file and compare it before replacement.",),
+        reference_urls=("https://www.sqlite.org/cli.html",),
+    ),
+    CommandExtensionSpec(
+        extension_id="command.database.supabase",
+        name="Supabase command protection",
+        description="Reviews database reset and migration rollback commands.",
+        action_classes=("Supabase destructive command",),
+        risk_classes=("destructive_shell", "network_egress"),
+        safer_alternatives=("Use --dry-run and verify the selected database target first.",),
+        reference_urls=("https://supabase.com/docs/reference/cli/supabase-db-reset",),
+    ),
+)

plugin_scanner-2.0.1097/src/codex_plugin_scanner/guard/runtime/command_database_matchers.py

@@ -0,0 +1,208 @@
+"""Structured matchers for database command-line grammars."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import final
+
+from .command_matcher_contracts import CommandMatcher, MatcherEvidence
+from .command_model import CanonicalCommand, CommandSegment
+from .command_structured_matchers import leading_flags_and_operands, present_flags
+
+
+@final
+@dataclass(frozen=True, slots=True)
+class ArgumentCommandMatcher:
+    """Match a command-like argument and its payload without scanning free-form text."""
+
+    executables: frozenset[str]
+    command: str
+    minimum_abbreviation_length: int
+    minimum_position: int = 0
+
+    def __post_init__(self) -> None:
+        normalized_executables = frozenset(value.strip().lower() for value in self.executables if value.strip())
+        normalized_command = self.command.strip().lower()
+        if not normalized_executables or not normalized_command:
+            raise ValueError("ArgumentCommandMatcher requires executables and a command")
+        if not 1 <= self.minimum_abbreviation_length <= len(normalized_command):
+            raise ValueError("ArgumentCommandMatcher has an invalid minimum abbreviation length")
+        if self.minimum_position < 0:
+            raise ValueError("ArgumentCommandMatcher minimum position cannot be negative")
+        object.__setattr__(self, "executables", normalized_executables)
+        object.__setattr__(self, "command", normalized_command)
+
+    def match(self, command: CanonicalCommand) -> tuple[MatcherEvidence, ...]:
+        evidence: list[MatcherEvidence] = []
+        for index, segment in enumerate(command.segments):
+            if not _segment_matches_executable(segment, self.executables):
+                continue
+            for argument in segment.arguments[self.minimum_position :]:
+                parts = argument.strip().lower().split(None, 1)
+                if len(parts) != 2:
+                    continue
+                command_token = parts[0]
+                if len(command_token) < self.minimum_abbreviation_length or not self.command.startswith(command_token):
+                    continue
+                evidence.append(
+                    MatcherEvidence(
+                        segment_index=index,
+                        executable=segment.executable,
+                        detail="Matched a structured command argument and required payload.",
+                    )
+                )
+                break
+        return tuple(evidence)
+
+
+@final
+@dataclass(frozen=True, slots=True)
+class CommandSequenceMatcher:
+    """Match target commands in a documented multi-command grammar."""
+
+    executables: frozenset[str]
+    command_arities: tuple[tuple[str, int], ...]
+    target_commands: frozenset[str]
+    options_with_values: frozenset[str] = frozenset()
+    forbidden_flags: frozenset[str] = frozenset()
+
+    def __post_init__(self) -> None:
+        normalized_executables = frozenset(value.strip().lower() for value in self.executables if value.strip())
+        normalized_arities = tuple((name.strip().lower(), arity) for name, arity in self.command_arities)
+        normalized_targets = frozenset(value.strip().lower() for value in self.target_commands if value.strip())
+        normalized_options = frozenset(
+            _normalize_option_token(value) for value in self.options_with_values if value.strip()
+        )
+        normalized_forbidden = frozenset(
+            _normalize_option_token(value) for value in self.forbidden_flags if value.strip()
+        )
+        command_names = tuple(name for name, _arity in normalized_arities)
+        if not normalized_executables or not command_names or not normalized_targets:
+            raise ValueError("CommandSequenceMatcher requires executables, commands, and targets")
+        if len(set(command_names)) != len(command_names) or any(arity < 0 for _name, arity in normalized_arities):
+            raise ValueError("CommandSequenceMatcher requires unique commands with non-negative arities")
+        if not normalized_targets <= frozenset(command_names):
+            raise ValueError("CommandSequenceMatcher targets must exist in the command grammar")
+        object.__setattr__(self, "executables", normalized_executables)
+        object.__setattr__(self, "command_arities", normalized_arities)
+        object.__setattr__(self, "target_commands", normalized_targets)
+        object.__setattr__(self, "options_with_values", normalized_options)
+        object.__setattr__(self, "forbidden_flags", normalized_forbidden)
+
+    def match(self, command: CanonicalCommand) -> tuple[MatcherEvidence, ...]:
+        evidence: list[MatcherEvidence] = []
+        arities = dict(self.command_arities)
+        command_names = tuple(arities)
+        for index, segment in enumerate(command.segments):
+            if not _segment_matches_executable(segment, self.executables):
+                continue
+            if any(
+                _normalize_option_token(argument.split("=", 1)[0]) in self.forbidden_flags
+                for argument in segment.arguments
+            ):
+                continue
+            _flags, operands = leading_flags_and_operands(
+                segment.arguments,
+                options_with_values=self.options_with_values,
+            )
+            operand_index = 0
+            while operand_index < len(operands):
+                token = operands[operand_index].strip().lower()
+                candidates = tuple(name for name in command_names if name.startswith(token))
+                if len(candidates) != 1:
+                    break
+                resolved_command = candidates[0]
+                if resolved_command in self.target_commands:
+                    evidence.append(
+                        MatcherEvidence(
+                            segment_index=index,
+                            executable=segment.executable,
+                            detail="Matched a destructive command in a structured command sequence.",
+                        )
+                    )
+                    break
+                operand_index += 1 + arities[resolved_command]
+        return tuple(evidence)
+
+
+@final
+@dataclass(frozen=True, slots=True)
+class LeadingSubcommandMatcher:
+    """Match subcommands after case-sensitive leading option parsing."""
+
+    executables: frozenset[str]
+    subcommands: tuple[str, ...]
+    options_with_values: frozenset[str] = frozenset()
+    forbidden_flags: frozenset[str] = frozenset()
+    required_flags_anywhere: frozenset[str] = frozenset()
+
+    def __post_init__(self) -> None:
+        normalized_executables = frozenset(value.strip().lower() for value in self.executables if value.strip())
+        normalized_subcommands = tuple(value.strip().lower() for value in self.subcommands if value.strip())
+        normalized_options = frozenset(
+            _normalize_option_token(value) for value in self.options_with_values if value.strip()
+        )
+        normalized_forbidden = frozenset(
+            _normalize_option_token(value) for value in self.forbidden_flags if value.strip()
+        )
+        normalized_required = frozenset(
+            value.strip().lower() for value in self.required_flags_anywhere if value.strip()
+        )
+        if not normalized_executables or not normalized_subcommands:
+            raise ValueError("LeadingSubcommandMatcher requires executables and subcommands")
+        object.__setattr__(self, "executables", normalized_executables)
+        object.__setattr__(self, "subcommands", normalized_subcommands)
+        object.__setattr__(self, "options_with_values", normalized_options)
+        object.__setattr__(self, "forbidden_flags", normalized_forbidden)
+        object.__setattr__(self, "required_flags_anywhere", normalized_required)
+
+    def match(self, command: CanonicalCommand) -> tuple[MatcherEvidence, ...]:
+        evidence: list[MatcherEvidence] = []
+        for index, segment in enumerate(command.segments):
+            if not _segment_matches_executable(segment, self.executables):
+                continue
+            leading_flags, operands = leading_flags_and_operands(
+                segment.arguments,
+                options_with_values=self.options_with_values,
+            )
+            lowered_operands = tuple(value.lower() for value in operands)
+            if self.forbidden_flags & leading_flags or lowered_operands[: len(self.subcommands)] != self.subcommands:
+                continue
+            matched_flags = present_flags(
+                tuple(argument.lower() for argument in segment.arguments),
+                options_with_values=self.options_with_values,
+            )
+            if not self.required_flags_anywhere <= matched_flags:
+                continue
+            evidence.append(
+                MatcherEvidence(
+                    segment_index=index,
+                    executable=segment.executable,
+                    detail="Matched executable and leading-option-aware subcommands.",
+                )
+            )
+        return tuple(evidence)
+
+
+def database_matcher_index_hints(matcher: CommandMatcher) -> tuple[frozenset[str], frozenset[str]] | None:
+    """Return conservative registry hints for database grammar matchers."""
+
+    if isinstance(matcher, ArgumentCommandMatcher):
+        return matcher.executables, frozenset({matcher.command})
+    if isinstance(matcher, CommandSequenceMatcher):
+        return matcher.executables, matcher.target_commands
+    if isinstance(matcher, LeadingSubcommandMatcher):
+        return matcher.executables, frozenset(matcher.subcommands)
+    return None
+
+
+def _segment_matches_executable(segment: CommandSegment, executables: frozenset[str]) -> bool:
+    if segment.executable is None:
+        return False
+    executable = segment.executable.replace("\\", "/").rsplit("/", 1)[-1].lower()
+    return executable in executables
+
+
+def _normalize_option_token(value: str) -> str:
+    stripped = value.strip()
+    return stripped.lower() if stripped.startswith("--") else stripped