Sentinel

AI-powered code guardian that uses Claude for framework-agnostic code review, security analysis, and API testing.

What It Does

Sentinel is a pre-push git hook that automatically analyzes your code changes before they reach the repository. It uses Claude AI to:

1. Quick Sanity Check - Catch obvious errors, syntax issues, and critical security vulnerabilities
2. Comprehensive Code Review - Deep analysis of code quality, security, potential bugs, and adherence to project guidelines
3. API Security Testing - Automatically detect, test, and validate API endpoints for functionality and security issues

The key difference: This tool is completely framework and language agnostic. It uses AI intelligence to understand any codebase, rather than hardcoded rules.

Features

• Framework Agnostic - Works with any language or framework (JavaScript, TypeScript, PHP, Python, Go, etc.)
• AI-Powered Analysis - Uses Claude Code for intelligent code review
• Security First - Blocks pushes with security vulnerabilities
• API Testing - Automatically detects and tests API endpoints
• Project-Aware - Reads CLAUDE.md for project-specific guidelines
• Customizable - Configure what issues should block vs. warn
• Detailed Reports - Terminal summaries + detailed markdown reports

Prerequisites

1. Node.js 18+ - Required to run the tool
2. Claude Code - Must be installed and available in PATH
   • Install from: https://claude.ai/download
   • Verify with: claude --version
3. Git - Must be a git repository

Installation

Global Installation (Recommended)

npm install -g @dusan.djordjevic/sentinel

Per-Project Installation

npm install --save-dev @dusan.djordjevic/sentinel

Quick Start

1. Navigate to your project:

   cd your-project

2. Initialize sentinel:

   sentinel init

   This will:

   • Create .sentinel/config.yml
   • Install the pre-push git hook
   • Set up reports directory
   • Update .gitignore

3. Customize configuration (optional): Edit .sentinel/config.yml to adjust blocking rules

4. Create CLAUDE.md (optional but recommended): Add project-specific guidelines, coding standards, and context

5. Push your code:

   git add .
   git commit -m "Your changes"
   git push  # <- The hook runs automatically here

Managing False Positives with Ignores

Sometimes the AI may flag code that you know is safe (false positives), or you may have intentional design decisions that trigger warnings. The ignores system lets you tell the tool to skip these sections while still using them for context.

Two Ways to Ignore Code

1. Inline Comments (Quick & Temporary)

Add a comment directly in your code:

// sentinel-ignore: Using Sequelize ORM - SQL injection prevented
const query = db.query('SELECT * FROM users WHERE id = ' + userId);

// sentinel-ignore
// Reason: Legacy endpoint scheduled for removal in v2.0
function oldApiEndpoint() { ... }

2. Ignores File (Permanent & Team-Wide)

Edit .sentinel/ignores.json:

{
  "ignores": [
    {
      "file": "src/api/users.js",
      "line": 45,
      "reason": "Using Sequelize ORM - SQL injection prevented"
    },
    {
      "file": "database/migrations/**",
      "line": "*",
      "reason": "Migration files reviewed separately"
    }
  ]
}

CLI Commands

# List all ignores
sentinel ignores list

# Add an ignore
sentinel ignores add src/api/users.js:45 "Using ORM"

# Ignore entire file
sentinel ignores add src/legacy.js:* "Legacy code"

# Remove an ignore
sentinel ignores remove src/api/users.js:45

# Check for stale ignores
sentinel ignores validate

Smart Validation

Claude doesn't just skip ignored code - it validates your ignore reasons:

⚠️ Questionable Ignores Detected:

1. src/api/users.js:45
   Ignore Reason: "Using ORM"
   Actual Issue: This is direct SQL concatenation, not ORM usage.
                 The ignore reason appears incorrect.
   Suggestion: Review this ignore - the code doesn't match the stated reason

This prevents dangerous code from hiding behind incorrect ignore reasons!

When to Use Ignores

✅ Good Use Cases:

• False positives (AI incorrectly flags safe code)
• Intentional design decisions with documented reasoning
• Legacy code under controlled review process
• Test fixtures and mock data

❌ Avoid:

• Hiding real security vulnerabilities
• Using vague reasons like "will fix later"
• Over-ignoring entire categories of issues

Configuration

The .sentinel/config.yml file controls the pipeline behavior:

version: 1

# What should block the push?
block_on:
  - security_vulnerabilities  # Any security issue blocks
  - critical_bugs             # Critical severity bugs block
  - api_security_issues       # API security issues block

# Should we test APIs if changes are detected?
test_apis: true

# Optional: Help Claude understand your project
project:
  type: "Laravel API"  # e.g., "React SPA", "Express API"
  description: "RESTful API for e-commerce platform"

# Optional: Exclude specific paths from analysis
exclude:
  - legacy-code/
  - generated/

CLAUDE.md Integration

Create a CLAUDE.md file in your project root to provide context to the AI:

# My Project

## Architecture
- Clean architecture with service layer
- Repository pattern for data access
- API versioning with /v1/, /v2/ prefixes

## Coding Standards
- Always use TypeScript strict mode
- Prefer functional components in React
- Use async/await over promises
- Validate all user input with Zod

## Security Requirements
- All API endpoints require JWT authentication
- Sanitize all database queries through Prisma ORM
- Rate limit all public endpoints

## Testing
- Unit tests required for all services
- E2E tests for critical user flows

The AI will use this context to provide project-specific analysis.

How It Works

Stage 1: Quick Sanity Check (30-60s)

Fast scan for obvious issues:

• Syntax errors
• Hardcoded secrets (API keys, passwords)
• Clear security vulnerabilities (SQL injection, XSS)
• Committed sensitive files (.env, credentials)

Result: Pass or Block

Stage 2: Comprehensive Code Review (2-5 min)

Deep analysis covering:

• Security: Injection vulnerabilities, auth issues, data exposure, crypto misuse
• Code Quality: Architecture violations, code smells, error handling
• Potential Bugs: Logic errors, race conditions, null checks, edge cases
• Project Standards: Adherence to CLAUDE.md guidelines

Result: Pass, Warn, or Block

Stage 3: API Testing (2-5 min, if applicable)

If API changes detected:

1. Identify new/modified endpoints
2. Detect where API is running (port, URL)
3. Generate test scenarios (functionality + security)
4. Execute tests against local API
5. Validate responses and security

Result: Pass or Block

Usage Examples

Manual Analysis

Run analysis without pushing:

sentinel analyze

Skip API Testing

sentinel analyze --skip-api

Verbose Output

sentinel analyze --verbose

Reinitialize (Force)

sentinel init --force

Reports

After each run, you'll get:

1. Terminal Summary - Immediate feedback on issues
2. Detailed Markdown Report - Saved to .sentinel/reports/

Example report location:

.sentinel/reports/2024-11-15T14-30-45-blocked.md

Reports include:

• Summary of all stages
• Detailed issue descriptions
• File locations and line numbers
• Suggestions for fixes
• Test results (if applicable)

Example Output

Success

🛡️  Sentinel Code Guardian Starting...

ℹ️  Gathering context...
✅ Analyzing 3 unpushed commit(s) on branch "feature/user-auth"
ℹ️  Changed files: 12

🔍 Stage 1: Quick Sanity Check
✅ Quick check passed
✅ No critical issues found in quick scan

🔍 Stage 2: Comprehensive Code Review
✅ Code review passed
✅ Code quality meets standards. 2 minor suggestions noted.

🔍 Stage 3: API Security & Testing
ℹ️  Found 2 endpoint(s), preparing tests...
⚠️  API testing requires your server to be running
ℹ️  Detected API URL: http://localhost:3000
Press Enter when your API is running...
✅ API tests passed
✅ Tested 8 scenarios successfully

──────────────────────────────────────────────────
✅ All Checks Passed - Push Allowed!
──────────────────────────────────────────────────

📄 Report saved to: .sentinel/reports/2024-11-15T14-30-45-passed.md

Blocked

🔍 Stage 2: Comprehensive Code Review
❌ Code review failed - blocking issues found

──────────────────────────────────────────────────
❌ PUSH BLOCKED - Issues found in Stage 2
──────────────────────────────────────────────────

Issues Found:

CRITICAL (2):

1. SQL Injection vulnerability in user query
   File: src/api/users.js:45
   Fix: Use parameterized queries or ORM

2. Hardcoded JWT secret in environment file
   File: .env:12
   Fix: Remove from .env and use environment variables

📄 Full report saved to: .sentinel/reports/2024-11-15T14-32-10-blocked.md

Troubleshooting

"Claude Code not installed"

Ensure Claude is installed and in your PATH:

claude --version

If not installed: https://claude.ai/download

"No unpushed commits found"

The tool only analyzes changes that haven't been pushed to the remote. Commit and push once to establish a baseline.

API tests failing

1. Ensure your API is running locally
2. Check the detected URL in the output
3. Verify the port matches your configuration
4. Use --skip-api to skip API testing if needed

Hook not running

1. Check if .git/hooks/pre-push exists and is executable
2. Reinstall: sentinel init --force
3. Verify git hooks aren't disabled: git config core.hooksPath

Development

Project Structure

sentinel/
├── src/
│   ├── index.js           # CLI entry point
│   ├── commands/          # Commands (init, analyze)
│   ├── core/              # Core logic (git, claude, orchestrator)
│   ├── stages/            # Three analysis stages
│   ├── reporters/         # Terminal and markdown reporters
│   └── utils/             # Logger, config loader
├── hooks/                 # Pre-push hook template
├── templates/             # Config template
└── package.json

Testing Locally

cd sentinel
npm install
npm link

# Now use in another project
cd ../your-test-project
sentinel init

FAQ

Q: Does this work with monorepos? A: Yes, it analyzes the entire diff from unpushed commits.

Q: What languages are supported? A: All languages - the AI understands any codebase.

Q: Can I customize the AI prompts? A: Currently no, but you can use CLAUDE.md to guide the analysis.

Q: Does this replace linters/formatters? A: No, it complements them. Use both for best results.

Q: How much does it cost? A: You need a Claude Code installation. Pricing depends on your Claude subscription.

Q: Can I use this in CI/CD (GitHub Actions, GitLab CI)? A: Currently designed for pre-push hooks. CI/CD integration coming soon.

License

MIT

Contributing

Contributions welcome! Please open an issue or PR.

Support

• Issues: https://bitbucket.org/itc-solution/sentinel/issues
• Repository: https://bitbucket.org/itc-solution/sentinel
• Docs: This README
• Claude Code: https://claude.ai/download