Sentinel CLI

A local security audit tool that behaves like a stack-aware security engineer. Sentinel CLI runs targeted security checks based on your technology stack and deployment environment.

Features

• Stack-Aware Scanning: Automatically selects relevant security checks based on your frontend, backend, and deployment environment
• Comprehensive Checks: Covers infrastructure, code, configuration, and cloud security
• Framework-Specific Rules: Specialized checks for Express, Django, Rails, Laravel, and Next.js
• Auto-Fix Capabilities: Automatically fixes safe security issues with confirmation
• Beautiful Output: Color-coded, human-readable results with severity indicators
• JSON Reports: Export scan results as JSON for CI/CD integration
• Cloud Dashboard: Automatically submit reports to sentinelcli.com for viewing and analytics

Installation

Global Installation (Recommended)

npm install -g @usama2762/sentinelcli

After installation, you can use sentinelcli from anywhere:

sentinelcli init
sentinelcli scan

Local Development

git clone https://github.com/CoalAI/sentinelcli.git
cd sentinelcli
npm install
npm run build
npm link  # Makes 'sentinelcli' available globally

Quick Start

1. Initialize configuration:

   sentinelcli init

   This will ask you three questions:

   • What's your frontend? (React / Vue / Next / HTML)
   • What's your backend? (Node / Python / Ruby / PHP)
   • Where does it run? (Linux server / AWS / Docker / Local machine)

2. Run a security scan:

   sentinelcli scan

3. Auto-fix issues (with confirmation):

   sentinelcli fix

4. Auto-fix all issues (no confirmation):

   sentinelcli fix --yes

Commands

sentinelcli init

Initialize Sentinel CLI configuration. Creates a .sentinelcli.json file in your project root.

sentinelcli scan

Run security scans based on your configuration. Reports are automatically submitted to sentinelcli.com for viewing in the dashboard.

Options:

• -j, --json <path>: Output JSON report to specified file
• --no-upload: Disable automatic report upload to sentinelcli.com
• -p, --project-name <name>: Specify project name for report submission

Example:

sentinelcli scan
sentinelcli scan --json report.json
sentinelcli scan --project-name "My Project"
sentinelcli scan --no-upload  # Skip dashboard upload

Environment Variables:

• SENTINELCLI_API_URL: Custom API URL (default: https://sentinelcli.com/api/reports)
• SENTINELCLI_ENABLED: Set to "false" to disable reporting (default: enabled)
• SENTINELCLI_DEBUG: Set to "true" for debug logging

sentinelcli fix

Apply auto-fixes for security issues. Only safe, non-destructive fixes are applied automatically.

Options:

• -y, --yes: Auto-approve all fixes without confirmation

Example:

sentinelcli fix
sentinelcli fix --yes

sentinelcli plugins

Manage plugins for extended functionality.

Subcommands:

• list: List available plugins
• install <plugin>: Install a plugin

Example:

sentinelcli plugins list
sentinelcli plugins install framework-nextjs

Security Checks

Infrastructure Checks

• Open Ports: Detects publicly exposed database and service ports
• SSH Configuration: Checks for root login and password authentication
• Outdated Packages: Identifies packages with available updates
• File Permissions: Verifies sensitive files have proper permissions

Docker Checks

• Root User: Flags containers running as root
• Missing HEALTHCHECK: Detects containers without health checks
• Secrets in Images: Finds hardcoded secrets in Dockerfiles
• Public Ports: Checks for 0.0.0.0 port bindings
• Docker Socket: Warns about mounted Docker sockets
• Resource Limits: Checks for missing resource constraints

Code Checks

• Hardcoded Credentials: Detects passwords, API keys, tokens, and secrets
• Dangerous Patterns: Finds eval(), unsafe exec(), SQL injection risks
• Exposed .env Files: Checks for environment files in public directories
• Error Logs: Detects publicly accessible log files
• Admin Panels: Identifies unprotected admin routes

Framework-Specific Checks

Express (Node.js)

• CORS configuration without origin restrictions
• Missing helmet middleware
• High body parser limits

Django

• DEBUG = True in production
• Hardcoded SECRET_KEY
• ALLOWED_HOSTS = ['*']
• Missing CSRF middleware

Rails

• Hardcoded secret_key_base
• Debug logging in production

Laravel

• APP_DEBUG=true
• .env in public directory
• Publicly accessible storage/logs

Next.js

• Exposed environment variables in publicRuntimeConfig

Cloud Checks (AWS)

• S3 Bucket Exposure: Checks for public S3 buckets
• Security Groups: Identifies open security groups (0.0.0.0/0)
• IAM Users: Flags users with administrative privileges

Note: AWS checks require AWS CLI to be installed and configured.

Output Format

Sentinel CLI provides color-coded output with severity indicators:

• 🔥 CRITICAL: Immediate security risks requiring urgent attention
• ⚠️ HIGH: Significant security issues that should be addressed soon
• • MEDIUM: Moderate security concerns
• i LOW: Minor issues or best practice recommendations

Each finding includes:

• Message: Description of the issue
• File & Line: Location of the issue (if applicable)
• Type: Category (server, code, config, cloud)
• Fix: Copy-paste command or instruction to resolve
• Explanation: Why this matters

Example Output

Security Scan Results
============================================================

Summary:
  Total issues: 5
  🔥 Critical: 2
  ⚠️  High: 2
  • Medium: 1

🔥 CRITICAL ISSUES

🔥 Hardcoded PostgreSQL password found
   File: backend/config.js:42
   Type: code
   Fix: Replace line with "const password = process.env.POSTGRES_PASSWORD"
   Why: Hardcoded DB credentials allow full database compromise.

🔥 Django DEBUG mode is enabled
   File: settings.py:25
   Type: config
   Fix: Set DEBUG = False in production
   Why: DEBUG mode exposes sensitive information including stack traces.

Configuration

Configuration is stored in .sentinelcli.json:

{
  "frontend": "React",
  "backend": "Node",
  "deployment": "AWS"
}

Development

# Install dependencies
npm install

# Build
npm run build

# Run in development mode
npm run dev

# Run tests
npm test

# Watch tests
npm run test:watch

Project Structure

sentinelcli/
├── src/
│   ├── cli/
│   │   ├── index.ts
│   │   └── commands/
│   │       ├── init.ts
│   │       ├── scan.ts
│   │       ├── fix.ts
│   │       └── plugins.ts
│   ├── scanners/
│   │   ├── linuxScanner.ts
│   │   ├── dockerScanner.ts
│   │   ├── awsScanner.ts
│   │   ├── secretsScanner.ts
│   │   ├── codeScanner.ts
│   │   └── frameworkScanner.ts
│   ├── utils/
│   │   ├── fileUtils.ts
│   │   ├── logger.ts
│   │   ├── parser.ts
│   │   ├── execUtils.ts
│   │   └── config.ts
│   ├── engine/
│   │   ├── ruleEngine.ts
│   │   └── resultFormatter.ts
│   └── types/
│       └── index.ts
├── tests/
├── package.json
├── tsconfig.json
└── README.md

Extending Sentinel CLI

Adding a New Scanner

1. Create a new scanner class implementing the Scanner interface:

import { Finding, Scanner } from "../types";

export class MyScanner implements Scanner {
  name = "My Scanner";

  async scan(): Promise<Finding[]> {
    const findings: Finding[] = [];
    // Your scanning logic
    return findings;
  }
}

2. Add it to the RuleEngine constructor.

Adding Framework Support

Extend FrameworkScanner or create a new scanner in the scanners/ directory.

Requirements

• Node.js 16+
• TypeScript 5+
• For AWS checks: AWS CLI installed and configured
• For Linux checks: Appropriate system permissions

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Security

If you discover a security vulnerability, please email [email protected] instead of using the issue tracker.