flaw

A fast static analysis tool for finding security flaws in Crystal code.

Installation • Quickstart • GitHub Action • Rules • Contributing • Changelog

flaw reads your Crystal source and holds it up to the light. Each rule looks for a specific security flaw — hardcoded secrets, command injection sinks, SQL built from interpolation, weak randomness used for tokens, untrusted YAML loads. Findings print with file and line, and can be emitted as JSON or SARIF for CI and GitHub Code Scanning.

Installation

From source

git clone https://github.com/kdairatchi/flaw.git
cd flaw
shards build --release --no-debug --production
./bin/flaw version

Homebrew (coming with v0.1.0 release)

brew install kdairatchi/tap/flaw

Pre-built binaries

Download from the Releases page — linux-amd64, linux-arm64, macos-arm64.

Quickstart

flaw scan .                              # scan current directory, pretty output
flaw scan src/ --format json             # JSON for agents / pipelines
flaw scan . --format sarif > flaw.sarif
flaw scan . --fail-on high               # CI: exit 1 if any high+ finding
flaw rules                               # list built-in rules, grouped by tag
flaw rules FLAW001                       # show rule detail
flaw lint-rules                          # validate rules/ directory contract
flaw init config                         # drop a .flaw.yml config stub
flaw init rule FLAW011 my-new-rule       # scaffold a new rule folder + detector

GitHub Action

# .github/workflows/flaw.yml
name: flaw
on: [push, pull_request]
jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: kdairatchi/flaw@v0.1.0
        with:
          args: scan . --fail-on high --format sarif > flaw.sarif
      - uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: flaw.sarif

Rules

Security (FLAW0xx)

AI-slop / hygiene (FLAW1xx)

Detects unedited LLM paste-through — the smell of vibe-coded Claude/ChatGPT output shipped without review. Novel territory: no other linter looks for these.

Every rule lives in its own folder under rules/ with the detector, a vulnerable fixture (bad.cr), a fixed version (good.cr), metadata (rule.yml), and docs. Add one with flaw init rule FLAW011 my-rule.

Rule validator

flaw lint-rules enforces the rule contract — every folder matches FLAWNNN, has all four required files, the rule.yml parses and has the required keys, the detector file exists, and each bad.cr + good.cr behaves as claimed. Run it in CI as the gatekeeper for rule contributions.

Configuration

.flaw.yml in your repo root:

version: 1
exclude:
  - spec/
  - lib/
  - vendor/
rules:
  FLAW002:
    ignore:
      - "examples/fake-keys.cr"
  FLAW004:
    severity: critical
  FLAW005:
    disabled: true

Roadmap

• v0.2 — 10 more rules, --fix autofix for trivial cases, better SARIF provenance
• v0.3 — LSP server (real-time flaws in your editor)
• v0.4 — Baseline file (gate only on new findings)
• v0.5 — Custom rule DSL (community rules in YAML)
• v0.6 — Cross-file taint tracking (sources → sinks)
• v1.0 — Plugin system, hosted rule docs at flaw.prowlrbot.com, Caido integration

Contributing

flaw is an open-source project built by one person and improved by many. See CONTRIBUTING.md for how to add a rule, report a false positive, or suggest a roadmap item.

Why "flaw"?

In gemology, a flaw is a fracture, inclusion, or imperfection inside a crystal — the thing a trained eye spots by catching the light right. flaw does the same for Crystal code: it holds your program up to the light and shows you the fractures before someone else does.

Security

Report suspected vulnerabilities privately — see SECURITY.md.

License

MIT © kdairatchi