Local AppSec Lab

A local application security engine and portable Agent Skill from AVIQEN, licensed under Apache-2.0.

Version 0.2.1 is experimental. Assess repositories you own or are authorized to test. Findings carry evidence and coverage limits; a scan cannot certify an application as secure.

The engine inventories source, runs bounded source and Python data-flow analysis, coordinates specialist AI workers with fresh verification and remediation workers, provisions supported locked dependencies and disposable Compose services, and tests actual local applications through scoped HTTP and Chromium. It produces JSON, Markdown, offline HTML and SARIF reports. Deterministic assessments require no model subscription or API key.

Install

Install the published package in your chosen Python environment:

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

Or install from source using the commands below.

Prerequisites: Python 3.11+, venv and pip; Git for cloning. Active execution also needs a supported OS isolation backend and a prepared runtime. Browser/database workflows require Docker with Linux containers. See the full prerequisites and installation guide.

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

Windows PowerShell, without activating scripts or changing execution policy:

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

Use the explicit Windows executable in subsequent examples when the environment is not active. The PyPI package and source checkout provide the same CLI and portable skill.

Use it

Replace /path/to/application with an authorized local repository:

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

Review does not execute application code. Configure a supported startup command and synthetic test policies, inspect the plan, then authorize execution with the plan_digest that plan printed. The scan is refused if the effective configuration has changed since:

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

A deliberately vulnerable fixture can exit 1 for a confirmed finding. Exit 2 means partial coverage; inspect blocked and untested checks. Read usage and exit codes and the configuration guide.

Optional AI and skill

Install the skill in a user or project directory:

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

Targets are Claude Code, Codex, Cursor, Gemini CLI and generic Agent Skills hosts. Installing files, invoking a skill, and running specialist model workers are distinct capabilities. Use host instructions and measured compatibility.

For automatic model workers, set ai.strategy: native, a positive limits.model_tokens budget and a bounded limits.model_calls, then explicitly authorize transmitting selected redacted context:

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

Claude, Cursor and Gemini have corresponding --native-host values. Authenticated CLIs must be installed separately. Native vendor token/cost caps are not uniformly enforceable; reports distinguish reserved and reported usage. Gemini's individual-account OAuth client was rejected by Google during testing; supported API/enterprise authentication is needed. See AI setup.

Capabilities and limits

Runtime recognition does not imply universal framework launch. Whole-program proof, arbitrary Compose files, inferred business policies, mobile emulators and ZAP execution are outside the implemented scope. Fix generation currently supports a narrow Python debug rewrite or a reviewed Python/JSON replacement. See the requirement-by-requirement status.

Consult validation for exact measured results and outstanding prerequisites.

Automatic PyPI updates

Merged PRs into main publish a new PyPI release after CI passes. The workflow chooses the next unused patch version, synchronizes package/CLI/changelog versions, validates the distributions, publishes with the existing Trusted Publisher, and verifies a fresh public installation. Direct pushes and unmerged PRs do not publish. See the release process for concurrency, retries and manual validation.

Documentation and development

• Installation, update and uninstall
• Usage, advanced workflows, configuration/schema
• Architecture, security model, framework support
• Troubleshooting, FAQ, report format
• Validation, requirements status, release procedure
• Contributing, security disclosure, third-party notices

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

Runtime tests need their documented platform and preloaded images. Never treat skipped integration tests as successful execution. Private .appsec-lab state contains local security evidence and must stay out of version control.

Native macOS Seatbelt is an explicit reviewed-source option. It cannot block every numeric same-user process-argument query; host process environment/arguments may be exposed. Use Docker for untrusted application or scanner code.