frapAST

Runtime-Proven Static Security and Performance Engine for Frappe and ERPNext

Find the vulnerability. Synthesize the reproducer. Prove it live. Ship the autofix.

Quickstart | Industry Benchmarks | Architecture Comparison | Developer Experience | Rule Taxonomy | Engine Architecture | Web Dashboard

Overview

Generic SAST tools analyze Frappe applications as generic Python scripts. Consequently, they fail to recognize that @frappe.whitelist() exposes a public HTTP endpoint, cannot resolve dynamic DocType schema permissions, miss string-literal dispatches such as frappe.call("dotted.path"), and generate significant false-positive noise.

frapAST is designed from the Frappe framework layer outward. It indexes DocType JSON schemas, parses hooks.py, walks module AST structures, and constructs an interprocedural static call graph modeling direct calls, string-based RPC dispatches, lifecycle hooks, dynamic document methods, and report execution entry points.

Candidate findings are scored across a multi-dimensional risk matrix and can be escalated through an Active Two-Tier Proof Engine that synthesizes standalone HTTP/RPC reproducers to verify exploitability against a running Frappe bench.

Industry Benchmarks and Performance

Evaluated against open-source enterprise Frappe codebases on macOS (Apple Silicon) and Linux (x86_64) using Python 3.10 through 3.14:

1. Throughput and Scalability

2. Empirical Detection Precision (Audited on Frappe HRMS)

Live-Bench Active Verification Case Study

frapAST includes live integration testing against local and staging Frappe benches. The Tier 2 proof engine generates and executes direct HTTP RPC reproducers to verify whether a static candidate is exploitable over the wire:

• Unprotected RPC Endpoint (frappe.client.get_time_zone):

  GET /api/method/frappe.client.get_time_zone HTTP/1.1 -> HTTP 200 OK
  {"message":{"time_zone":"Asia/Kolkata"}}
  [PROVEN]: Endpoint permits unauthenticated guest execution.
  

• Protected RPC Endpoint (frappe.auth.get_logged_user):

  GET /api/method/frappe.auth.get_logged_user HTTP/1.1 -> HTTP 403 Forbidden
  {"exc_type":"PermissionError","message":"You are not permitted to access this resource"}
  [REFUTED]: Endpoint enforces authentication guard.
  

Architectural Comparison

Data Privacy and Air-Gapped Execution

frapAST is engineered with strict data confidentiality:

1. Zero Data Egress: All parsing, AST traversal, call graph generation, and proof execution run locally on 127.0.0.1. No telemetry or source code is transmitted externally.
2. Confidentiality by Design: No company names, client data, or proprietary identifiers are stored or required. All references in reports adhere strictly to open-source repository paths.
3. Local Origin Gating: The web dashboard is bound exclusively to localhost and enforces origin headers against unauthorized cross-origin requests.

Quickstart

Installation

# Install via pip
pip install frapast

# Or install in editable mode for development
pip install -e .

1. Launch the Visual Dashboard

frapast
# Automatically starts local server and opens http://localhost:7777

2. Run a CLI Security and Performance Audit

# Perform static scan
frapast scan /path/to/frappe-app

# Perform scan with active bench verification
frapast scan /path/to/frappe-app --prove --bench-url http://localhost:8000

# Export SARIF 2.1.0 for GitHub Code Scanning
frapast scan /path/to/frappe-app --format sarif > results.sarif

3. Apply Automated Fixes via CLI

Note: Automated code remediation is provided via the command-line interface (frapast fix) and the Python library. It is intentionally decoupled from the web dashboard REST API.

# Preview AST modifications as unified diffs (dry-run)
frapast fix /path/to/frappe-app

# Apply modifications directly to source files
frapast fix /path/to/frappe-app --apply

Developer Experience (DX)

1. Native Frappe Bench CLI (bench frapast)

frapAST registers directly into Frappe's native bench CLI:

# Run security and performance audit on an app
bench frapast audit my_custom_app

# Apply automated security patches
bench frapast fix my_custom_app --apply

# Verify live HTTP exploitability on an active bench site
bench frapast prove my_custom_app --site dev.local

# Diagnose bench connectivity and port availability
bench frapast check --port 8000

2. Reusable GitHub Action

Add .github/workflows/frapast.yml to your repository for automated PR security checks and SARIF Code Scanning alerts:

name: frapAST Security Audit

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main, develop ]

jobs:
  security-audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run frapAST Audit
        uses: pratheep-bit/frapast@v0.1.0
        with:
          repo-path: '.'
          fail-on: 'critical'
          upload-sarif: 'true'

3. Automated Autofix Engine (frapast fix)

Automated AST patch generation handles routine security boilerplate:

• FR-HOOK-001: Automatically generates symmetrical on_cancel(self) methods for DocTypes implementing on_submit.
• FR-HOOK-004: Injects deduplicate=True into frappe.enqueue() calls.
• FR-HOOK-006: Replaces bare except: blocks with except Exception: to preserve framework execution signals.
• FR-PERM-001: Injects frappe.only_for("System Manager") permission checks into unguarded mutating endpoints.

Rule Taxonomy

frapAST includes 28 active rule detectors and 2 explicitly disabled rules across core security and operational areas:

Proof Basis:
  Tier 2 : Live HTTP/RPC verification against a running Frappe bench
  Tier 1 : Standalone local AST reproducer (independent of bench)
  Static : Structural code pattern and dataflow verification

Injection and Access Control

Authorization and Permission Enforcement

Framework Lifecycle and Workflow Integrity

Performance, Correctness and Reliability

How It Works

+-----------------+   +-----------------+   +-----------------+
|  Schema Index   |   |   Hook Index    |   |  Python AST     |
|  (DocType JSON) |   |  (hooks.py AST) |   |  (Source Files) |
+--------+--------+   +--------+--------+   +--------+--------+
         |                     |                     |
         +---------------------+---------------------+
                               |
                      +--------v--------+
                      |   Call Graph    |  5 Edge Types:
                      |                 |  - direct_call
                      |                 |  - string_dispatch (frappe.call)
                      |                 |  - hook_dispatch (doc_events)
                      |                 |  - dynamic_method (get_doc.method)
                      |                 |  - report_entry (report.execute)
                      +--------+--------+
                               |
                      +--------v--------+
                      |   Rule Engine   |  28 Active Detectors
                      +--------+--------+
                               |
                      +--------v--------+
                      | Severity Matrix |  Multi-Dimensional Composite Scoring
                      +--------+--------+
                               |
            +------------------+------------------+
            |                                     |
   +--------v-------+                    +--------v-------+
   |  CLI / SARIF   |                    | Web Dashboard  |
   +--------+-------+                    +--------+-------+
            |                                     |
            +------------------+------------------+
                               |
                      +--------v--------+
                      |  Proof Engine   |  Tier 0 (Static) -> Tier 1 (AST) -> Tier 2 (HTTP/RPC)
                      +--------+--------+
                               |
                      +--------v--------+
                      | Autofix Engine  |  CLI AST Code Patch Generator and Diff Viewer
                      +-----------------+

1. Schema and Hook Indexing: Parses all DocType JSON definitions (fields, permissions, is_submittable, istable) and hooks.py dispatch trees.
2. AST Parsing and Call Graph Construction: Analyzes AST structures to extract whitelisted endpoints, database calls, parameters, string-literal dispatches (frappe.call("dotted.path")), and script report entry points (execute(filters)).
3. Composite Severity Matrix: Computes severity using required privileges (guest vs authenticated user), impact classification, and blast radius.
4. Active Proof Verification:
   • Tier 1 (AST Proof): Standalone verification programs executed locally.
   • Tier 2 (HTTP/RPC Proof): Authenticated HTTP requests executed by FrappeHTTPClient against a Frappe bench.
5. Autofix Engine: Automatically generates and applies AST modifications via the CLI to eliminate manual boilerplate updates.

Interactive Web Dashboard

Launch the local web dashboard:

frapast

Features provided in the web interface:

• Real-Time Scan Streaming: Server-Sent Events (SSE) update the dashboard as files are processed.
• Visual Proof Drawer: Inspect synthesized reproducers and view live verification outcomes.
• Bench Connectivity Diagnostics: Test connection to local Frappe bench instances with diagnostic reporting.
• Persistent Storage: SQLite with WAL mode preserves scan and proof history across application restarts.

Test Suite and Quality Assurance

The codebase includes an automated test suite:

pytest -v

• 293 passed tests covering AST visitors, call graph resolution, rule detectors, server security, reproducer synthesis, adversarial suppression handling, and autofix patches.
• Security hardening: Hardened shell script generation (shlex.quote), path traversal directory containment, and localhost origin gating.

Contributing

Contributions are welcome. To report an architectural pattern or false-positive edge case:

1. Fork the repository
2. Create your feature branch (git checkout -b feature/new-rule)
3. Run tests (pytest)
4. Commit your changes and submit a Pull Request

License

MIT (c) 2026 Frappe Security Scanner Contributors - see LICENSE.