Sentinel

Developer-focused secret scanner for GitHub Actions, local CLI, and a SQLite-backed dashboard.

Requirements

• Node.js 20+
• npm 11+

Run

npm install
npm run db:generate
npm test
npm run dev

Open http://localhost:3000, choose a repository .zip, and run a scan. Uploads are limited to 20 MB, extracted into a temporary directory, and deleted after the masked findings have been saved.

Quality checks:

npm run typecheck
npm run lint
npm run format:check
npm run build

Scanner

@sentinel/scanner recursively scans text files without executing repository code. It ignores dependency/build directories, symlinks, binary files, and files over 1 MB by default. Findings contain masked values only.

import { scanDirectory } from "@sentinel/scanner";

const result = await scanDirectory("./project");

Current rules cover AWS, GitHub, Slack, and Google keys; private keys; credentialed database URLs; hardcoded passwords; JWTs; generic API keys; sensitive .env values; and suspicious high-entropy strings.

CLI

Build the workspace, then scan a local directory:

npm run build
node cli/dist/index.js scan ./my-project
node cli/dist/index.js scan ./my-project --json

GitHub Action

Scan pull requests and main with the repository action:

name: Sentinel

on:
  pull_request:
  push:
    branches: [main]

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: <owner>/sentinel@v1
        with:
          path: .
          fail-on: none

path defaults to .. fail-on accepts none, low, medium, high, or critical; none reports findings without failing CI. Outputs are findings (masked JSON), files-scanned, and highest-severity. The action scans only the checked-out workspace and creates file/line annotations plus a job summary.

Use the CLI for the same local scan behavior. Review findings before enabling a gate: pattern scanners can flag test values, examples, or non-secret identifiers. Never unmask a finding in logs. If a finding is real, revoke/rotate the credential, remove it from history where appropriate, and replace it through a secret manager.

Release immutable tags such as v1.2.3, then move the major tag (v1) to the latest compatible release so workflows can use @v1.

Database

SQLite is the local MVP default. Create or update the schema with:

npm run db:generate
npm run db:migrate -- --name <migration-name>

Security

Sentinel reduces common secret-exposure risks but cannot prove that a repository is secure. Treat every finding as sensitive, rotate exposed credentials, and use a dedicated secret manager. Never scan untrusted code with tools that execute it.

Uploaded archives are validated before extraction: traversal paths and symlinks are rejected; archive entry, per-file, and expanded-size limits prevent resource abuse. Sentinel only reads text files and never stores uploaded source code.

See THREAT_MODEL.md for the upload boundary and deployment risks.

Workspace

• apps/web — Next.js application
• packages/scanner — framework-independent scanner
• cli — local repository scanner CLI

Status

The scanner, CLI, dashboard foundation, and reusable GitHub Action are available.