Devrail 🛤️

Security & Quality Guardrails — Adoption-first developer discipline

Stop fighting your team about guidelines. Devrail blocks mistakes automatically and lets you adopt security incrementally with baseline + diff-only mode.

devrail:
  preset: "node-api"  # Auto-detected!
  level: "standard"
  baseline: ".devrail/baseline.json"  # Accept existing, block new

Quick Start (3 minutes)

# Install
npm install -g devrail

# Initialize - auto-detects your stack!
npx devrail init

# See what's wrong
npx devrail check

# Fix safe issues automatically
npx devrail fix

# Accept existing issues, block only NEW ones
npx devrail baseline

Why Devrail?

The problem: Vibecoding is fun until you ship secrets to GitHub, forget input validation, or deploy with 47 critical vulnerabilities.

The solution: Opinionated guardrails that:

• ✅ Block secrets in code (gitleaks)
• ✅ Block vulnerable dependencies (osv-scanner)
• ✅ Block dangerous patterns (semgrep)
• ✅ Enforce tests & coverage
• ✅ Generate CI pipelines automatically

Presets

| Preset | Description | |--------|-------------| | node-api | Express, Fastify, Koa backends | | nextjs-app | Next.js full-stack apps | | python-api | FastAPI, Flask, Django (coming soon) | | cli-tool | CLI applications | | library | npm/PyPI packages | | monorepo | Multi-package repositories |

Levels

| Level | Description | |-------|-------------| | basic | Low friction, maximum adoption. Only critical issues. | | standard | Recommended default. Balanced security + quality. | | strict | Hard blocking. For mature teams. |

CLI Commands

devrail init              # Auto-detect stack, bootstrap config
devrail check             # Fast local check
devrail check --changed   # Only check changed files (PR mode)
devrail ci                # Full CI check (blocking)
devrail fix               # Apply safe automatic fixes
devrail fix --all         # Include fixes that need review
devrail baseline          # Accept existing issues
devrail baseline --update # Update baseline with current state
devrail explain <rule>    # Explain a rule + how to fix
devrail rules             # List all rules

Rules (30 MVP)

Secrets

• secrets.no-plaintext — Detect hardcoded secrets
• secrets.no-env-commit — Block .env files in git
• secrets.gitignore-required — Ensure proper .gitignore

Dependencies

• deps.lockfile.required — Require lockfile
• deps.no-unpinned — Warn about ^, ~, * versions
• deps.no-git-deps — Block git:// dependencies
• deps.no-vulnerable — Scan for CVEs
• deps.no-typosquatting — Detect malicious packages
• deps.license-check — Check license compatibility

Security

• security.headers.required — Require security headers
• security.cors.safe-default — Block origin: *
• security.no-eval — Block eval/Function
• security.no-unsafe-regex — Detect ReDoS patterns
• security.no-prototype-pollution — Block prototype pollution

Auth

• auth.no-weak-jwt — Block weak JWT configs
• auth.no-hardcoded-credentials — Block hardcoded creds
• auth.session-secure — Require secure cookies

API

• api.validation.required — Require input validation
• api.rate-limiting — Require rate limiting
• api.no-sensitive-logging — Block PII in logs

SQL

• sql.no-string-concat — Block SQL injection patterns
• sql.no-raw-queries — Prefer ORM

Tests

• tests.unit.required — Require test files
• tests.coverage.min-50 — 50% coverage minimum
• tests.coverage.min-80 — 80% coverage (strict)
• tests.no-skipped — Block .skip()/.only()

Logging

• logging.no-pii — Block PII in logs
• logging.no-console — Use proper logger

Code Quality

• code.no-any — Block TypeScript any
• code.strict-mode — Require TS strict
• code.no-unused-vars — Remove dead code

Config

• config.node-version — Specify Node version
• config.editor-config — Require .editorconfig

Configuration

Full Config Example

devrail:
  preset: "node-api"
  level: "standard"
  
  # Baseline: accept existing, block new
  baseline: ".devrail/baseline.json"

  # Override specific rules
  rules:
    secrets.no-plaintext:
      enabled: true
      severity: error
    deps.no-unpinned:
      enabled: false  # Disable this rule
    tests.coverage.min-80:
      enabled: true
      blocking: false  # Warn but don't fail

  # CI settings
  ci:
    failOn: error  # error | warn | info
    reportFormat: console  # console | json | sarif

  # Tool toggles
  tools:
    eslint: true
    semgrep: true
    gitleaks: true
    osvScanner: true

  # File patterns
  include:
    - "src/**/*"
  exclude:
    - "**/*.test.ts"
    - "dist/**"

Config File Locations

Devrail looks for config in:

• devrail.config.yaml
• devrail.config.yml
• devrail.config.json
• devrail.config.js
• .devrailrc
• package.json (under devrail key)

CI Integration

GitHub Actions

# .github/workflows/devrail.yml
name: Devrail Security
on: [push, pull_request]

jobs:
  security:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci
      - run: npm install -g devrail
      - run: devrail ci --format sarif > results.sarif
      - uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: results.sarif

GitLab CI

devrail:
  image: node:20
  script:
    - npm ci
    - npm install -g devrail
    - devrail ci --fail-on error

Tool Requirements

Devrail wraps existing best-in-class tools:

| Tool | Purpose | Install | |------|---------|---------| | gitleaks | Secret scanning | brew install gitleaks | | osv-scanner | Dependency vulnerabilities | brew install osv-scanner | | semgrep | SAST | pip install semgrep |

Devrail gracefully skips tools that aren't installed.

Philosophy

1. Opinionated — We make decisions so you don't have to
2. Composable — Mix presets and rules like Tailwind classes
3. Frictionless — 10-minute setup, not 10-day integration
4. Blocking — Fail fast, fix early
5. Wrapper-based — We don't reinvent scanners, we orchestrate them

Key Innovation: Adoption-First

Unlike other tools that dump 400 errors on day one, Devrail:

1. Baseline - Accept existing issues, only block NEW ones
2. Diff-only - By default, only scan changed files in PRs
3. Auto-fix - Safe fixes applied automatically
4. Levels - Start with basic, graduate to strict

Roadmap

• [x] Baseline system (accept existing, block new)
• [x] Auto stack detection
• [x] Diff-only mode
• [ ] ESLint integration with security rules
• [ ] Python preset (pytest, bandit, safety)
• [ ] Watch mode (devrail guard --watch)
• [ ] VS Code extension
• [ ] Custom rule definitions

Contributing

git clone https://github.com/your-org/devrail
cd devrail
npm install
npm run dev

License

MIT