night_owl

NightOwl is AI-Augmented,high performance static analysis tool that detects business logic vulnerabilities across web & mobile stacks with mathematically verified exploitability and near-zero false positives. It fuses hybrid rule matching, data-/control-flow analysis, symbolic execution (Z3), and optional AI classifiers (ONNX) — all wrapped in a clean CLI and interactive HTML reports.

Why NightOwl?

Traditional SAST shines on injection bugs but routinely misses logic flaws (IDOR, price tampering, auth/role mistakes, unsafe payment flows) or floods you with FPs. NightOwl is designed to address these issues:

• Zero-FP pipeline — Rule hits are confirmed via data-flow and symbolic execution to produce concrete PoCs.
• Business-logic aware — A unified AST + context builder tags nodes as Authentication, Authorization, PaymentProcessing, InventoryManagement, etc.
• AI-assisted — ONNX classifiers provide framework-aware hints and confidence boosting without sending code to the cloud.
• Exploit proof — Z3-based constraints derive inputs (e.g., {"price": -100}) that satisfy the vulnerable path.
• Framework intelligence — Django, React, Flutter, Spring and more via framework-specific rules and pattern libraries.
• Ergonomic UX — Colorized terminal output for fast triage; interactive HTML with collapsible PoCs for sharing.

Features at a Glance

• Unified AST across languages (Tree-sitter) with cross-file CFG and taint/data-flow.

• Rule Engine (TOML) with framework & universal packs (Django, React, Flutter, Swift, Universal).

• Context Builder to propagate risks across edges and cluster business flows.

• Symbolic Executor (Z3) to verify exploitability and synthesize model-backed PoCs.

• ONNX Runtime integration for business-logic classification and risk signals.

• Strict Mode to gate findings behind nuclear verification.

• Two entry modes:

  • scan — multi-file project reconnaissance
  • audit — single-file / function-focused deep dive

• Reports:

  • Terminal: high-contrast “battle assessment”
  • HTML: interactive PoCs, copy-ready remediation

• Configurable via .nightowl.toml (rules/models paths, strictness, integrations).

Quick Start

Requirements

• Rust ≥ 1.75 (stable)
• Python ≥ 3.9
• Z3: linked statically via the z3 crate (no system install needed for standard builds)
• Linux/macOS/WSL2 recommended

Build

cargo build --release

The binary will be at target/release/nightowl. If you keep nightowl.rs at repo root, ensure Cargo.toml has:

[[bin]]
name = "nightowl"
path = "nightowl.rs"

CLI Reference (--help)

nightowl --help
                 _       .                            .  
 , __   `   ___. /      _/_             __.  ,  _  /  |  
 |'  `. | .'   ` |,---.  |            .'   \ |  |  |  |  
 |    | | |    | |'   `  |            |    | `  ^  '  |  
 /    | /  `---| /    |  \__/ ______,  `._.'  \/ \/  /\__
           \___/              '                                                                         

NightOwl — AI-Powered Static Analysis with minimal False Positives

USAGE:
  nightowl <COMMAND> [OPTIONS]

COMMANDS:
  scan        Scan an entire project (cyber reconnaissance)
  audit       Audit a single file (surgical strike)
  report      Generate a standalone report from results
  train       Train/retrain AI models
  verify      Run live exploit verification (staging/production)
  update      Update rules and threat intelligence
  help        Show help

GLOBAL FLAGS:
  -d, --debug                   Enable debug/forensics logs
  -a, --assurance <1..3>        Nuclear verification level (default: 3)

SCAN FLAGS:
  -p, --path <DIR>              Project directory to scan (required)
  -s, --strict                  Enforce nuclear verification on all hits
  -f, --format <text|json|html> Output format (default: text)
  -m, --mode <quick|deep|paranoid> Scan depth (default: deep)
  -o, --output <FILE>           Save results to file

AUDIT FLAGS:
  -f, --file <PATH>             Source file to audit (required)
  -t, --target <REGEX>          Narrow to function/symbol via regex
  -d, --deep                    Enable deep analysis (loops, sinks, multi-source taint)
  -F, --format <text|json|html> Output format (default: text)
  -o, --output <FILE>           Save results to file

REPORT:
  nightowl report <INPUT.json> [--format text|html|pdf]

TRAIN:
  nightowl train [--mode quick|full|paranoid]

VERIFY:
  nightowl verify <VULN_ID> [--target staging|production]

UPDATE:
  nightowl update

Usage Examples

1) Minimal project scan

nightowl scan --path ./apps/shop

2) Strict mode + HTML report

nightowl scan --path ./apps/shop --strict --format html --mode deep --output results/shop_deep.json

3) Targeted audit of one function

nightowl audit --file services/orders.py --target "checkout_total|apply_discount" --deep --format text

4) Train (paranoid) and export ONNX models

nightowl train --mode paranoid

5) Verify a specific finding

nightowl verify DJ001 --target staging

6) Update signatures

nightowl update

FAQ — Five Questions You Should Ask

1. How does NightOwl keep false positives low? Rule hits must pass data-flow plausibility and, in strict mode, symbolic execution to produce a concrete exploit input before they’re reported.

2. Can NightOwl catch business logic bugs like price tampering or IDOR? Yes — it’s built for that. Payment and authorization flows are first-class categories in the unified AST and rule packs.

3. Do I need the AI model to get value? For now. AI is optional. The core engine (rules + CFG/DFG + Z3) works out-of-the-box. ONNX is an enhancement for large codebases and framework nuance.

4. Will my code leave my machine? No. Everything runs locally. Models are loaded from disk; there’s no default telemetry.

5. How hard is it to author custom rules? Very easy — TOML with code/AST patterns and per-framework scoping. See docs/RULE_REFERENCE.md.

Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

🛠️ Troubleshooting

• Build fails linking Z3: ensure you are on a recent Rust (≥ 1.75). The crate uses static linking; if your platform needs system Z3, install via your package manager or disable the static-link-z3 feature.
• ONNX runtime missing: build with default features, or set --features ai-integration in Cargo.
• HTML report not generated: pass --format html or run nightowl report results.json --format html.
• Workspace vs. single crate: if you keep nightowl.rs at repo root, add the [[bin]] entry in Cargo.toml as shown above.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Author

Elie Uwimana 😎

• LinkedIn

Compliance & Ethics

⚠️ Authorized Use Only — NightOwl is designed for:

• Penetration testing with explicit written permission
• Bug bounty programs within platform guidelines
• Government and enterprise security validation
• Academic research in controlled environments