custos

Custos is a terminal-native security sidekick that scans outgoing Git diffs before push, explains risks with AI, patches issues, and makes overrides authenticated and auditable.

Comment

Inspiration

Modern security tools often detect vulnerabilities after code has already reached GitHub, CI, or a security dashboard. We wanted to move security earlier in the development process.

Custos was inspired by the idea of “extreme shift-left security”: stopping risky code at the exact moment a developer tries to push it, while the code and its context are still local and understandable.

The goal was not to create another passive scanner. Custos is designed as an interactive security decision point inside the terminal that catches vulnerabilities exposed in new changes.

What it does

Custos installs a local Git pre-push hook that scans outgoing changes before they leave the developer’s machine.

When a finding is detected, Custos:

  • Extracts and parses the outgoing Git diff.
  • Runs deterministic security rules against changed lines.
  • Uses Backboard AI for bounded security review and contextual explanations.
  • Redacts sensitive values before sending code context to AI.
  • Shows the severity, file, line, evidence, explanation, and recommendation.
  • Offers actions such as viewing details, applying a suggested patch, aborting, or overriding.
  • Blocks critical and high-severity findings by default.
  • Forces a patch to exit with a blocking status so developers must review and recommit.
  • Uses Auth0 Device Authorization Flow for authenticated overrides.
  • Records security findings and override decisions in MongoDB Atlas.
  • Provides custos doctor for environment and integration checks.
  • Provides custos audit for reviewing the audit ledger.

The package is publicly installable:

npm install --global @kylekhai/custos
custos init

How we built it

Custos is a TypeScript and Node.js command-line application distributed through npm.

The main workflow is: git push

-> pre-push hook

-> custos scan --pre-push

-> outgoing Git diff

-> deterministic rules + Backboard AI review

-> terminal security finding

-> patch, inspect, override, or abort

-> MongoDB audit event

The main technologies and integrations are:

  • TypeScript and Node.js for the CLI.
  • Commander.js for command routing.
  • Git pre-push hooks for local enforcement.
  • Execa for safe Git and process execution.
  • Backboard.io REST APIs for AI-powered explanation, contextual review, and patch generation.
  • Zod for validating external AI responses.
  • Auth0 Device Authorization Flow for identity verification in CLI environments.
  • Auth0 JWKS validation for verifying issued identity tokens.
  • MongoDB Atlas and Mongoose for structured audit events.
  • Chalk, Boxen, Gradient String, and @clack/prompts for terminal interaction and visual feedback.
  • Vitest, ESLint, and the TypeScript compiler for validation.
  • npm for global package distribution.

The AI system is intentionally bounded. Custos sends only relevant diff context, added lines, nearby context, and limited dependency information. AI enriches deterministic findings but does not replace local blocking rules.

Challenges we ran into

One major challenge was making the Git hook reliable. A pre-push hook must never crash, hang, or silently allow a push because an integration failed. We designed graceful fallbacks for unavailable AI, Auth0, or MongoDB services.

Another challenge was creating useful AI context without sending entire files or repositories. Custos needed enough context for Backboard to reason about security while still limiting exposure of source code and secrets.

We also had to handle unreliable model output. AI responses can vary in formatting and structure, so responses are normalized and validated with Zod before being used.

The Auth0 integration presented a separate challenge because CLI authentication is different from browser-based application login. Device Authorization Flow allows a terminal user to authenticate through a browser without requiring a client secret in the CLI.

Finally, patching required careful safety boundaries. Custos must never silently modify code and allow the same push. Applied patches always block the push so the developer can review, stage, commit, and push again.

Accomplishments that we're proud of

We are proud that Custos creates a complete security workflow before code leaves the local machine.

The core demo works end to end:

  1. A developer runs custos init.
  2. Custos installs a Git pre-push hook.
  3. A vulnerable change is committed.
  4. The developer attempts to push.
  5. Custos detects and explains the issue.
  6. The developer can apply a suggested fix or abort.
  7. A critical override requires authenticated identity.
  8. The decision is recorded in MongoDB Atlas.

We are also proud of the integration design:

  • Backboard AI performs contextual security analysis while deterministic rules remain the enforcement foundation.
  • Auth0 turns an override into an authenticated security decision rather than an anonymous bypass.
  • MongoDB Atlas provides a queryable audit history instead of ephemeral terminal output.
  • Secret values are redacted before AI review.
  • AI-only findings are grounded against supplied evidence and bounded by confidence.
  • The CLI is packaged for installation through npm.
  • The tool remains useful locally even when optional cloud integrations are unavailable.

What we learned

We learned that developer security tooling must be fast, clear, and integrated into an existing workflow. A security warning that interrupts development without explaining what to do next is easy to ignore.

We also learned that AI is most useful when constrained by deterministic systems. Local rules provide predictable enforcement, while AI adds context, prioritization, explanations, and remediation guidance.

CLI authentication requires a different architecture from web authentication. Auth0 Device Authorization Flow provides a practical way to authenticate users from a terminal without embedding secrets in the local application.

We learned that security tools need strong failure behavior. External services can be unavailable, models can return malformed data, and network calls can time out. None of those cases should cause the Git hook to behave unpredictably.

Most importantly, we learned that security decisions should be visible and accountable. Custos does not remove developer judgment; it makes that judgment easier to understand and records when a risky decision is intentionally approved.

What's next for custos

  • Expand dependency analysis with typo-squatting and transitive dependency detection.
  • Generate security reports and scan summaries for developers and teams.
  • Add MCP support and configurable audit filters.
  • Improve language support, patch validation, and CI integrations.
  • Add organization policies and customizable security rules.

Built With

Share this project:

Updates