local-appsec-lab 0.2.3

Website · Install · Quick start · How it works · AI & skill · Docs · Security

Local AppSec Lab is an open-source application security engine and portable Agent Skill from AVIQEN. It reviews your source, starts your app in a sandbox, tests it with synthetic users, and reports only what it can back with evidence. Your code stays on your machine. Deterministic assessments need no model subscription or API key.

✨ Why Local AppSec Lab

🧭 How it works

Three modes control how far a run goes:

📦 Install

From PyPI

python -m pip install local-appsec-lab
appsec-lab doctor

From source (macOS / Linux)

git clone https://github.com/aviqentech/local-appsec-lab.git
cd local-appsec-lab
python3 -m venv .venv
. .venv/bin/activate
python -m pip install .
appsec-lab doctor

git clone https://github.com/aviqentech/local-appsec-lab.git
cd local-appsec-lab
py -3 -m venv .venv
.\.venv\Scripts\python.exe -m pip install .
.\.venv\Scripts\appsec-lab.exe doctor

Prerequisites: Python 3.11+, venv and pip; Git for cloning. Running applications also needs a supported isolation backend and a prepared runtime. Browser and database workflows need Docker with Linux containers. See the installation guide for updates and uninstalling.

🚀 Quick start

Point it at a repository you are authorized to test:

appsec-lab inspect --project /path/to/application
appsec-lab plan    --project /path/to/application
appsec-lab scan    --project /path/to/application --mode review
appsec-lab report  --project /path/to/application --run latest --format html

To test the running app, add a startup command and synthetic scenarios to appsec-lab.yaml, review the plan, then authorize with the plan_digest it printed. The scan is refused if the effective configuration changed since you reviewed it:

appsec-lab scan  --project /path/to/application --mode local-active --authorize --plan-digest PLAN_DIGEST
appsec-lab clean --project /path/to/application

version: 1
execution:
  command: [node, server.js]
  port: 8765
  health_path: /health
limits:
  requests_per_second: 10
  max_requests: 100
scenarios:
  - id: cross-user-record
    path: /records/42
    category: authorization
    owner_headers: { X-Test-User: alice }
    actor_headers: { X-Test-User: bob }
    marker: SYNTHETIC_ALICE_RECORD_42

Exit codes

A zero exit status never means the application is secure. Read the report's coverage too. More in usage.

🤖 AI workers and agent skill

Install the skill for your coding agent, per user or per project:

python -m local_appsec_lab.install --global --target all
# Or: python -m local_appsec_lab.install --project /path/to/application --target codex

Targets: Claude Code, Codex, Cursor, Gemini CLI and generic Agent Skills hosts. Installing files, invoking a skill and running model workers are separate capabilities; see integrations.

For automatic specialist workers, set ai.strategy: native with a positive limits.model_tokens budget and bounded limits.model_calls, then explicitly allow sending selected, redacted context:

appsec-lab scan --project /path/to/application --mode review \
  --native-host codex --allow-model-requests

claude, cursor and gemini are also valid --native-host values; their CLIs must be installed and signed in separately. Vendor token and cost caps aren't uniformly enforceable, so reports separate reserved from reported usage. Gemini's individual-account OAuth client was rejected by Google in testing; use supported API or enterprise authentication. Details in AI setup.

🧰 Capabilities

Not in scope yet: whole-program proof, arbitrary Compose files, inferred business policies, mobile emulators and ZAP execution. Recognizing a runtime doesn't mean every framework can be launched. Fix generation covers a narrow Python debug rewrite or a reviewed Python/JSON replacement. See the requirement-by-requirement status.

🖥️ Platform support

Exact measured results and open prerequisites are in validation.

🛡️ Safety model

• Authorization is per run. --authorize binds the repository fingerprint, plan digest, mode, port, categories, budgets and expiry. Changed source or configuration is rejected.
• Loopback only. Requests go to explicit 127.0.0.1 / ::1 on the approved port; redirects, proxies, encoded or mapped addresses and other hosts are refused.
• Synthetic data only. State-changing tests need disposable synthetic data and an explicit rollback.
• Untrusted output. Model and scanner output can't run commands; the parent checks categories, source spans and evidence, and model findings stay candidates until verified.
• Private state. .appsec-lab/ holds local security evidence and must stay out of version control.

Read the full security model.

📚 Documentation

🔄 Releases

Every pull request merged into main publishes a new PyPI release once CI passes. The workflow picks the next unused patch version, syncs package, CLI and changelog versions, validates the distributions, publishes through the Trusted Publisher and verifies a fresh public install. Direct pushes and unmerged PRs don't publish. See the release process.

🛠️ Development

python -m pip install '.[dev]'
make lint
python -m pytest -q
python -m build

Runtime tests need their documented platform and preloaded images. A skipped integration test is not a successful one.

🤝 Contributing and security

Contributions are welcome. Start with CONTRIBUTING and the code of conduct. Report vulnerabilities privately as described in SECURITY, not in public issues.

📄 License

Apache-2.0. See LICENSE and NOTICE.

appsec.aviqen.com
_{Built by AVIQEN · Assess only what you own or are authorized to test.}