Home Docs Getting Started

Getting Started with frapAST

A comprehensive quickstart guide to running static audits, live HTTP proofs, and automated security fixes on Frappe & ERPNext applications.

1. Installation

frapAST is distributed as a standard Python package supporting Python 3.10 through 3.14 on macOS, Linux, and Windows.

# Install from PyPI
pip install frapast

# Or install in editable mode for local development
git clone https://github.com/pratheep-bit/frapast.git
cd frapast
pip install -e .

2. Running Your First Static Scan

To audit an application, point frapAST to the app directory. frapAST automatically discovers all Python source files, indexes DocType JSON schemas, parses hooks.py, and constructs an interprocedural static call graph.

# Run static audit
frapast scan /path/to/frappe-app

# Include detailed severity scores and multi-dimensional risk matrix
frapast scan /path/to/frappe-app --severity

# Export findings as machine-readable JSON
frapast scan /path/to/frappe-app --format json > findings.json

3. Active Two-Tier Proof Verification

To eliminate false positives, frapAST includes a two-tier proof verification engine that synthesizes executable reproducers:

  • Tier 1 (AST Reproducers): Standalone Python scripts executed locally to verify structural logic defects.
  • Tier 2 (HTTP/RPC Proofs): Authenticated HTTP requests dispatched against a live local or staging Frappe bench.
# Perform static scan and verify candidates against live bench
frapast scan /path/to/frappe-app --prove --bench-url http://localhost:8000

# Prove a specific finding ID
frapast prove /path/to/frappe-app --finding-id FR-PERM-001-001 --bench-url http://localhost:8000

4. Automated Code Remediation (Autofix)

frapAST includes an AST-level remediation engine capable of previewing and applying code patches for common security patterns:

# Preview unified diffs without modifying files (dry-run)
frapast fix /path/to/frappe-app

# Apply synthesized patches directly to source files on disk
frapast fix /path/to/frappe-app --apply

# Filter fixes to a specific rule (e.g. FR-HOOK-001 missing on_cancel)
frapast fix /path/to/frappe-app --rule FR-HOOK-001 --apply

5. Next Steps

Explore the rest of the documentation: