Sentinel Dependency Guard

Guards against unauthorized or risky dependency additions by validating packages before installation completes.

When to Use This Hook

Attach this hook when you need to:

• Prevent installation of blacklisted, deprecated, or known-vulnerable packages before they enter your dependency tree
• Enforce organizational policies on approved package registries and license types for all dependency additions
• Alert the team when new dependencies are added that exceed size thresholds or introduce transitive dependency bloat

Consider alternatives when:

• Your project uses a lockfile-based workflow with a separate security scanning tool like Snyk or Dependabot that already covers this
• You are working on personal prototypes where dependency governance adds friction without meaningful security benefit

Quick Start

Configuration

Copy
name: sentinel-dependency-guard
type: hook
trigger: PreToolUse
category: automation

Example Trigger

Copy
npm install lodash
# Hook intercepts before execution:
# Sentinel: Validating dependency "lodash"...

Example Output

Sentinel Dependency Guard: Validation Report
Package: [email protected]
License: MIT (APPROVED)
Size: 72KB (within threshold)
Known Vulnerabilities: 0
Transitive Dependencies: 0
Deprecation Status: Active
Registry: npmjs.org (APPROVED)
Decision: ALLOW

Core Concepts

Dependency Validation Overview

Aspect	Details
Trigger Point	PreToolUse on Bash commands matching install patterns
Validation Checks	License, vulnerability, size, deprecation, registry source
Blocklist Source	Configurable .claude/dependency-blocklist.json in project root
Policy Engine	Rule-based evaluation with allow, warn, and block outcomes
Package Managers	npm, yarn, pnpm, pip, cargo, go modules
Response Time	Validation completes within 5-10 seconds per package

Guard Evaluation Workflow

Install Command Detected
    |
    v
[Parse package name + version] --> [Query registry API]
    |                                    |
    v                                    v
[Check blocklist] <----------- [Fetch metadata]
    |                                    |
    v                                    v
[Evaluate policies]            [Check vulnerabilities]
    |                                    |
    +------------------------------------+
    |
    v
[ALLOW / WARN / BLOCK] --> [Output report]
    |
   BLOCK --> Exit code 2 (prevents installation)

Configuration

Parameter	Type	Default	Description
blocklist_file	string	.claude/dependency-blocklist.json	Path to the JSON file containing explicitly blocked package names
allowed_licenses	string	MIT|Apache-2.0|BSD-3-Clause|ISC	Pipe-separated list of approved license identifiers
max_package_size	string	5MB	Maximum acceptable size for a single package before triggering a warning
max_transitive_deps	integer	50	Maximum number of transitive dependencies a package may introduce
vulnerability_action	string	block	Action to take when vulnerabilities are found: block, warn, or ignore

Best Practices

1. Maintain a living blocklist document - Update the dependency blocklist as part of your regular security review cycle. Include a comment field for each blocked package explaining why it was blocked and what approved alternative should be used instead, so developers understand the reasoning.

2. Start with warn mode before enforcing blocks - When first deploying the guard, set the default action to warn rather than block. This gives your team time to identify false positives and refine the policy rules before the guard starts preventing legitimate installations.

3. Align license policies with your legal team - The approved license list should reflect your organization's actual legal requirements. Consult with legal counsel to determine which open-source licenses are compatible with your product's distribution model before configuring the guard.

4. Monitor transitive dependency growth - A package with few direct dependencies may pull in dozens of transitive dependencies. Set the max_transitive_deps threshold based on your project's tolerance for supply chain complexity and review packages that approach the limit.

5. Cache registry lookups for offline resilience - Network requests to package registries can fail or be slow. Configure the guard to cache validation results locally so repeated installations of the same package version complete instantly and the guard remains functional during network outages.

Common Issues

1. Guard blocks legitimate internal packages - If your organization publishes packages to a private registry, the guard may not recognize the registry as approved. Add your private registry URL to the allowed_registries configuration to prevent false blocks on internal packages.

2. Validation timeout on large dependency trees - When installing multiple packages simultaneously, the guard may exceed its timeout while validating each package sequentially. Increase the timeout or configure parallel validation to handle bulk installation commands.

3. False vulnerability reports for patched versions - Vulnerability databases sometimes lag behind package releases. If a package version has been patched but the vulnerability database has not been updated, the guard may incorrectly block it. Use version-specific allowlist entries to override known false positives.