@dailephd/my-dev-kit-lab 0.4.0 → 0.4.2

package/README.md

@@ -1,78 +1,300 @@
 # my-dev-kit-lab
 
-my-dev-kit-lab is the experiment, evidence, reporting, visualization, and security-validation companion for my-dev-kit. It provides controlled raw-full-file versus graph-guided retrieval experiments, deterministic fake-agent demonstrations, reports, plots, gallery artifacts, generic audits, and local security-validation workflows.
+> Current release state: v0.4.1 is the latest published baseline. v0.4.0 delivered the Android validation MVP; v0.4.1 delivered advanced Android security. v0.4.2 is implemented and release-prepared (package metadata `0.4.2`) but not yet published. Manual pentest is post-v1 / version TBD.
 
-The current published baseline is `v0.3.4`. The v0.4.0 Android validation implementation is release-prepared on `release/v0.4.0`; publication is pending. It is not published, and the npm registry latest version remains `0.3.4`.
+my-dev-kit-lab is the experiment, evidence, reporting, security-validation, and audit companion for my-dev-kit. It runs reproducible experiments that test whether my-dev-kit's graph-guided retrieval helps coding-agent workflows, collects metrics, renders reports, generates plots, captures screenshots, builds gallery outputs, performs automated CLI/package security validation, and runs the generic audit framework.
+
+The generic experiment-plugin framework was introduced in `v0.2.0`. Its first plugin, `context-strategy-comparison`, preserves the raw-full-file vs my-dev-kit-guided comparison through the plugin runner. Later releases added the generic audit framework, language-aware code-rot detectors for TypeScript/JavaScript, Python, Java, and Kotlin, a security-validation audit adapter, and Android validation. See [CHANGELOG.md](CHANGELOG.md) for the complete release history.
+
+my-dev-kit is most useful when the repository is larger than the task. It helps coding agents work with large codebases through reusable structural indexing, graph-guided retrieval, targeted source slices, and auditable context selection. Results are scoped evidence; the project does not claim that my-dev-kit always saves tokens.
+
+**my-dev-kit** is the repo indexing and graph-guided retrieval engine.
+**my-dev-kit-lab** is the separate lab layer that feeds it benchmark inputs and records evaluation outputs.
+
+---
 
 ## Current capabilities
 
-- Controlled experiment plugins, reports, plots, screenshots, and gallery artifacts.
-- Generic code-rot and general security audit types through `npm run audit`.
-- Standalone CLI/package security validation through `npm run security:validate`.
-- Android security validation through the canonical `android` profile on the v0.4.0 feature branch.
+- Benchmark projects at small, medium, and large complexity levels
+- Project complexity metrics and benchmark case metadata with answer keys
+- Prompt variant generation at `short`, `medium`, `long`, and `multi-step` complexity levels
+- Fake-agent adapter for deterministic smoke and demo validation
+- Codex and Claude adapters for real-agent campaigns
+- Controlled experiment runner comparing `raw-full-file` vs `my-dev-kit-guided` strategies
+- Deterministic correctness scoring from answer keys
+- Token usage, duration, and status comparisons between matched strategy pairs
+- HTML experiment report rendering
+- Static SVG plot generation
+- Optional PNG screenshot capture
+- Gallery manifest and static gallery index output
+- Visualization demos using my-dev-kit commands against benchmark projects
+- Final demo workflow combining all pipeline stages
+- Generic experiment-plugin command surface: `experiment:list`, `experiment:describe`, and `experiment:run`
+- First experiment plugin: `context-strategy-comparison`
+- Target-aware experiment execution for local projects via `experiment:run -- --target <path>`
+- Plugin-aware JSON and HTML reports with plugin, target, variant, metric, artifact, warning, skip, and failure metadata
+- Security validation framework: dependency audit, package tarball inspection, CLI adversarial tests, static scans (CodeQL/Semgrep), bounded fuzz smoke, attack-scenario checks, and structured verdict/report output — runnable against any local project via `security:validate --target <path>`. `security:validate` remains the standalone, focused security-validation command; it is not replaced by the audit adapter below.
+- Generic audit framework: `npm run audit` runs conservative code-rot and security detectors and writes text/JSON reports under `reports/audits/` by default. `code-rot` and `security` are the currently implemented audit types (`--types code-rot`, `--types security`, or combined `--types code-rot,security`); `quality`, `project`, and `all` audit types are planned and fail cleanly instead of running. Audit does not modify target files and does not auto-fix issues. See [docs/COMMANDS.md](docs/COMMANDS.md) for full flags.
+- Language-aware code-rot detectors for TypeScript/JavaScript, Python, Java, and Kotlin, built on a shared source-facts model and normalized language/file-role inventory. Java/Kotlin support is conservative static analysis only: no compiler parsing, type/classpath resolution, or Gradle/Maven execution.
+- Security-validation audit adapter: `npm run audit -- --types security` runs the same `security:validate` internals through the shared audit/report surface, mapping findings into audit issues and linking back to the original `reports/security/` report. `security:validate`'s own checks and reports are unaffected.
+- Android validation: `security:validate --profile android` runs nineteen static checks against an Android project (manifest, permissions, exported components, network security config, backup/release configuration, secrets, signing, WebView/FileProvider, sensitive storage/logging, and Firebase/Google services), with optional opt-in Gradle operations and external tools (Semgrep, OSV-Scanner, Android Lint, Dependency-Check). Default execution starts zero Gradle processes, zero external tools, and zero network operations.
+- Android-aware generic audit: `npm run audit -- --types security --android` runs the same static Android validation through the audit adapter, mapping confirmed findings into audit issues while keeping review-only `CandidateEvidence` separate and never treated as a confirmed issue.
 
-## Android validation
+---
 
-Run static Android validation with:
+## Architecture overview
 
-```powershell
-npm run security:validate -- --target "<android-project-path>" --profile android
+```mermaid
+flowchart TD
+  A[scripts/experiments] --> B[Experiment plugin registry + runner]
+  B --> C[context-strategy-comparison]
+  C --> D[Controlled experiment foundations]
+  D --> E[Plugin + legacy artifacts]
+  E --> F[Plugin-aware reports]
+  E --> G[Plots / screenshots / gallery]
+  H[scripts/security] --> I[Automated security validation]
+  I --> J[Security reports + verdict]
+  I --> K[Android validation]
+  L[scripts/audits] --> M[Generic audit framework]
+  M --> N[Code-rot detectors]
+  M --> I
 ```
 
-This default path executes **no Gradle commands**. It detects/classifies Android projects and UI evidence, parses discovered manifests independently, audits permissions/exported components/intent filters/deep links, extracts static Gradle metadata, assembles release metadata and Play-readiness placeholders, calculates an Android verdict, and writes bounded text and JSON reports.
+---
 
-Reports use the existing `reports/security/` root unless `--out` is supplied. Android report files use the `<prefix>-android-security-validation.txt` and `.json` convention.
+## Quickstart
 
-Optional Gradle validation is explicit:
+### Install
 
-```powershell
-npm run security:validate -- --target "<android-project-path>" --profile android --android-gradle-operations wrapper-version,tasks
+```bash
+npm install
+```
+
+The same command works in PowerShell and `cmd.exe`.
+
+### Build
+
+```bash
+npm run build
+```
+
+### Verify the installation
+
+```bash
+npm run verify
+```
+
+### Run the fake-agent final demo (deterministic, no external CLIs required)
+
+```bash
+npm run run-final-demo -- \
+  --cases examples/token-savings-cases.json \
+  --out lab-output/final-demo \
+  --kit-command "node tests/fixtures/fake-my-dev-kit-cli.js" \
+  --agents fake-agent \
+  --complexities short \
+  --no-screenshot
 ```
 
-The only allowed operation IDs are:
+```powershell
+npm run run-final-demo -- `
+  --cases examples/token-savings-cases.json `
+  --out lab-output/final-demo `
+  --kit-command "node tests/fixtures/fake-my-dev-kit-cli.js" `
+  --agents fake-agent `
+  --complexities short `
+  --no-screenshot
+```
 
-- `wrapper-version`
-- `tasks`
-- `assemble-debug`
-- `unit-test-debug`
-- `lint-debug`
+```bat
+npm run run-final-demo -- --cases examples/token-savings-cases.json --out lab-output/final-demo --kit-command "node tests/fixtures/fake-my-dev-kit-cli.js" --agents fake-agent --complexities short --no-screenshot
+```
 
-Unknown or empty lists, arbitrary tasks, and use with a non-Android profile are rejected. Optional operations can require Java, Android SDK components, wrapper distributions, and cached dependencies; environment gaps can produce skipped or inconclusive evidence.
+The lab resolves Windows `.cmd` and `.ps1` CLI shims, supports command paths with spaces, and keeps generated artifacts inside the requested output directory.
 
-### Verdicts
+This runs a full pipeline: controlled experiment → report → plots → visualization demos → gallery.
 
-- `not-ready-security-blocker-remains`: a blocker remains.
-- `inconclusive-audit-environment-incomplete`: required evidence/environment is incomplete.
-- `ready-except-optional-manual-checks`: advisory or manual follow-up remains.
-- `ready-for-release-preparation`: required static evidence passed.
+### Run a real-agent campaign (requires Codex or Claude CLI)
 
-These are validation-evidence states, not claims that an app is published, Play-ready, Play-compliant, runtime-secure, or signing-valid.
+```bash
+npm run run-controlled-experiment -- \
+  --cases examples/real-agent-campaign-cases.json \
+  --agents codex,claude \
+  --strategies raw-full-file,my-dev-kit-guided \
+  --complexities medium,multi-step \
+  --out lab-output/real-agent-campaign \
+  --include-real-agents \
+  --continue-on-failure \
+  --timeout-ms 240000
+```
 
-### Important Android limitations
+Real-agent runs require local Codex or Claude CLI setup and available usage capacity. Runs that time out, produce invalid output, or hit session limits are recorded as structured outcomes rather than failures.
 
-- Static analysis does not prove runtime behavior.
-- Manifests are not merged; placeholders and resource references are not resolved.
-- Gradle scripts are not evaluated; dynamic metadata can stay unresolved; same-file duplicate assignment extraction uses the first match.
-- Optional Gradle execution is disabled by default and environment-dependent.
-- APK/AAB contents, signing, emulator/device behavior, Digital Asset Links, domain ownership, and live Google Play policy are not validated.
-- Play Console items such as privacy policy, Data Safety, permissions declarations, store listing, release notes, content rating, and policy review remain manual placeholders.
+### List, describe, and run experiment plugins
 
-## Development
+```bash
+npm run experiment:list
+npm run experiment:describe -- --experiment context-strategy-comparison
+npm run experiment:run -- \
+  --experiment context-strategy-comparison \
+  --target /path/to/local/project \
+  --agents fake-agent \
+  --complexities short \
+  --no-screenshot
+```
 
 ```powershell
-npm run typecheck
-npm run build
-npm run test
-npm run verify
+npm run experiment:list
+npm run experiment:describe -- --experiment context-strategy-comparison
+npm run experiment:run -- `
+  --experiment context-strategy-comparison `
+  --target "Z:\Users\newuser\Projects\my-dev-kit-v1" `
+  --agents fake-agent `
+  --complexities short `
+  --no-screenshot
 ```
 
-Use `npm run security:validate -- --help` for command usage. Help does not run validation or write reports.
+When `--target` is omitted, the experiment runs in self mode against my-dev-kit-lab. When `--target <path>` is provided, the lab remains the tool root and the target project is inspected separately. Generated experiment outputs stay under lab-controlled output directories by default, not inside the target project.
+
+---
+
+## Where to find outputs
+
+| Artifact | Location |
+|---|---|
+| Experiment summary | `lab-output/<experiment>/experiment-summary.json` |
+| All runs | `lab-output/<experiment>/experiment-runs.json` |
+| Strategy comparisons | `lab-output/<experiment>/experiment-comparisons.json` |
+| HTML report | `lab-output/<report>/experiment-report.html` |
+| Report JSON | `lab-output/<report>/experiment-report.json` |
+| Report screenshot | `lab-output/<report>/experiment-report.png` |
+| Plugin experiment report JSON | `lab-output/experiments/<plugin>/<target>/<run>/report.json` |
+| Plugin experiment report HTML | `lab-output/experiments/<plugin>/<target>/<run>/report.html` |
+| Plot data | `lab-output/<plots>/plot-data.json` |
+| SVG charts | `lab-output/<plots>/charts/*.svg` |
+| Gallery manifest | `lab-output/<gallery>/gallery-manifest.json` |
+| Gallery index | `lab-output/<gallery>/gallery-index.html` |
+
+---
+
+## How to read the main report
+
+Open `experiment-report.html` in a browser. The report shows:
+
+- **Project profile** — benchmark project name, language mix, complexity score, and file tree
+- **Benchmark tasks** — task descriptions and answer keys
+- **Strategy comparisons** — paired `raw-full-file` vs `my-dev-kit-guided` runs per case
+- **Correctness scores** — deterministic answer-key scoring (not semantic LLM judging)
+- **Token usage** — estimated or reported token totals per run
+- **Token savings** — positive means my-dev-kit used fewer tokens; negative means it used more
+- **Duration** — wall-clock time per run
+- **Status** — completed, timeout, invalid-output, or limit-reached
+- **Warnings and limitations** — notes on missing token totals or partial results
+
+See [docs/METRICS.md](docs/METRICS.md) for full metric definitions.
+
+---
+
+## Current limitations
+
+- Token savings shown in fake-agent runs are based on estimated character counts, not provider billing telemetry
+- Claude does not expose token totals; token savings comparisons are unavailable for Claude runs
+- Codex may expose token totals but can produce timeouts or invalid-output runs
+- Small projects may make raw-full-file cheaper than my-dev-kit-guided; larger localized tasks are where my-dev-kit is expected to become more useful
+- The generic experiment-plugin framework currently ships one plugin, `context-strategy-comparison`; future plugins such as warm-index reuse, incremental-change, and context-window scaling are not implemented yet
+- The current baseline does not prove token savings are guaranteed; it produces auditable evidence for specific cases, targets, agents, and strategies
+- Provider telemetry dashboards, semantic LLM judging, and cloud API billing integration are not yet implemented
+
+---
+
+## Roadmap direction
+
+my-dev-kit-lab is at a working baseline. The raw-vs-indexed experiment pipeline is fully implemented and produces reproducible artifacts, and real-agent campaign support exists for Codex and Claude. Recent releases added language-aware code-rot detectors (TypeScript/JavaScript, Python, Java, Kotlin), a security-validation audit adapter, and Android validation with an Android-aware extension of that same adapter.
+
+- `v0.4.0` and `v0.4.1`: Android automated security validation (published)
+- `v0.4.2`: Android-aware extension of the existing security audit adapter (see [CHANGELOG.md](CHANGELOG.md) for release status)
+- manual pentest: post-v1 / version TBD
+
+See [docs/ROADMAP.md](docs/ROADMAP.md) for the complete, versioned plan.
+
+---
+
+## Security validation
+
+my-dev-kit-lab owns a release-security validation track for **my-dev-kit**. This work is separate from the experiment pipeline and does not replace the generic experiment-plugin roadmap. Its purpose is to generate release-validation evidence for the local CLI/package before release preparation.
+
+`security:validate` remains the standalone, focused command for this validation and is unaffected by the current checked-out state. `npm run audit -- --types security` additionally adapts the same `security:validate` internals into the shared audit/report surface (mapped issues, a `securitySummary` field, and links to the original `reports/security/` output) — it does not replace or duplicate `security:validate`'s own checks or reports.
+
+This is not a web application pentest framework. **my-dev-kit** is a local CLI/package, so the validation model is CLI/package adversarial testing focused on whether it remains:
+
+- local-first
+- deterministic
+- read-only with respect to user source files
+- network-free during normal CLI operation
+- LLM-free
+- database-free
+- safe to run on local repositories
+
+The automated validation gate is implemented. It combines static scans, dependency/package checks, adversarial CLI tests, bounded fuzz smoke tests, and attack-scenario checks with structured text/JSON reports and a four-category verdict.
+
+### Security commands
+
+| Command | Description |
+|---|---|
+| `npm run security:deps` | npm audit, OSV-Scanner (if available), outdated packages |
+| `npm run security:package` | npm pack --dry-run, forbidden content detection |
+| `npm run security:codeql` | CodeQL CLI availability check; skipped gracefully when absent |
+| `npm run security:semgrep` | Semgrep scan via local binary or npx; skipped gracefully when both absent |
+| `npm run test:security` | Automated security and adversarial CLI tests (path traversal, read-only boundaries, malformed artifacts, JSON safety, and related checks) |
+| `npm run test:fuzz:smoke` | 9 bounded fuzz targets, seeded PRNG, completes in under 1 second |
+| `npm run security:validate` | Runs selected security checks, applies profile-aware defaults when requested, and writes text/JSON reports according to `--format` |
+
+CodeQL, Semgrep, and OSV-Scanner are optional. When unavailable locally, they are recorded as `skipped` in the report, not as passed. That can lead to `ready except optional manual checks`; it does not silently turn missing tooling into a clean pass.
+
+Each security command can validate my-dev-kit-lab itself or another local project via `--target <path>`. When `--target` is omitted, the framework performs self-validation. Target projects are inspected in place: their source files are not modified by default, generated artifacts stay under `reports/security/` unless `--out` is used, and external-target reports identify the tool root, target root, target package metadata, target git metadata, command cwd, exit code, and stdout/stderr summaries.
+
+`security:validate` supports `--checks`, `--profile`, `--format`, `--fail-on`, `--out`, and `--report-prefix`. The no-flag path remains backward compatible and still runs the classic implemented check groups: `deps`, `package`, `static`, `cli-adversarial`, and `fuzz`. Supplying `--profile` without `--checks` swaps in that profile's default checks; supplying explicit `--checks` always wins over profile defaults.
+
+The current attack-scenario checks cover boundary, subprocess, secrets, and network assumptions. They are automated adversarial checks, not a manual pentest. Manual pentest is deferred until after `v1.0.0`. `verdictImpact` metadata from each registered scenario drives blocker categorization in report reasoning, and narrowed `--checks` runs are labeled as scoped rather than described as a full release gate.
+
+JSON report poisoning/config-injection checks use a baseline-diff schema guard so legitimate additive JSON fields do not fail the guard while payload-created trusted top-level fields still do. Text reports are sanitized to strip ANSI/control-byte payloads before rendering.
+
+Known limits remain intentionally explicit: secret scanning is bounded rather than exhaustive, the network/local-first check is a bounded static assumption check rather than proof of runtime isolation, package-boundary severity is still result-level rather than per-evidence-item, and profile-specific scenario behavior is limited to profile-based scenario selection/default checks.
+
+For external-target validation, `security:validate` reads the target `package.json`, detects `scripts.test:security`, and runs `npm run test:security` in the target project root when that script exists. This behavior is validated both from the source checkout and from an installed packed tarball because published-package execution differs from local source execution.
+
+Generated security reports under `reports/security/` are excluded from git by default. They are produced locally or in CI as release-gate evidence and are not committed to the repository.
+
+See [docs/COMMANDS.md](docs/COMMANDS.md) for full command options and [docs/security-validation-framework.md](docs/security-validation-framework.md) for the security model, implemented modules, and release verdicts.
+
+---
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for the full text.
+
+---
+
+## Support
+
+my-dev-kit-lab is an independent project by dailephd LLC, developed and maintained by Dai Le.
+
+If this project helps your workflow, you can support continued development through GitHub Sponsors or PayPal:
+
+- [Sponsor on GitHub](https://github.com/sponsors/dailephd)
+- [Support via PayPal](https://paypal.me/daile88)
+
+Support is optional and does not affect access to the project.
 
-## Roadmap status
+---
 
-- `v0.4.0`: Android validation MVP — release-prepared; publication pending.
-- `v0.4.1`: planned advanced Android security checks.
-- `v0.4.2`: planned Android extension of the existing security audit adapter; it will not replace `security:validate`.
-- Manual pentest: deferred post-v1 / version TBD; not part of v0.4.x.
+## Documentation
 
-See [docs/PROJECT_OVERVIEW.md](docs/PROJECT_OVERVIEW.md), [docs/COMMANDS.md](docs/COMMANDS.md), [docs/WORKFLOWS.md](docs/WORKFLOWS.md), [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md), and [docs/ROADMAP.md](docs/ROADMAP.md).
+- [docs/PROJECT_OVERVIEW.md](docs/PROJECT_OVERVIEW.md) — product purpose and target users
+- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) — current and future architecture
+- [docs/WORKFLOWS.md](docs/WORKFLOWS.md) — step-by-step workflows with diagrams
+- [docs/COMMANDS.md](docs/COMMANDS.md) — all commands with options and examples
+- [docs/TUTORIAL.md](docs/TUTORIAL.md) — first-run walkthrough
+- [docs/METRICS.md](docs/METRICS.md) — metric definitions and interpretation
+- [docs/ROADMAP.md](docs/ROADMAP.md) — current baseline and future phases
+- [docs/GALLERY.md](docs/GALLERY.md) — gallery output explained

package/dist/scripts/audits/runAudit.js

@@ -20,9 +20,29 @@ import { writeAuditReports } from "../../src/audits/report/writeAuditReports.js"
 // ---------------------------------------------------------------------------
 const USAGE = "Usage: npm run audit -- [--target <path>] [--types code-rot,security] " +
     "[--include docs,tests,package,architecture,cli] [--format text,json] " +
-    "[--fail-on blocker|high|medium|low|none] [--out <path>]";
+    "[--fail-on blocker|high|medium|low|none] [--out <path>] [--android]\n" +
+    "\n" +
+    "  --android opts into Batch 2's programmatic Android security integration.\n" +
+    "  Requires --types to include \"security\" (e.g. --types security or --types\n" +
+    "  code-rot,security). Runs the same static, read-only, nineteen-check\n" +
+    "  Android validation security:validate --profile android performs --\n" +
+    "  detection, manifest parsing, and internal advanced security checks --\n" +
+    "  through the existing security adapter, never a subprocess. Confirmed\n" +
+    "  findings are mapped into the normal issue collection; CandidateEvidence\n" +
+    "  remains a separate, bounded summary and is never treated as a confirmed\n" +
+    "  issue. Starts zero Gradle operations, zero external tools, and zero\n" +
+    "  network operations by default; --android does not expose any of those.\n" +
+    "  Example: npm run audit -- --target \"<android-project-path>\" --types security --android --format text,json --fail-on none";
 const rawArgs = process.argv.slice(2);
 const toolRoot = resolveToolRoot(import.meta.url);
+// Help deliberately wins over every other argument, mirroring
+// scripts/security/validate.ts -- no config normalization, target
+// resolution, audit execution, or report write.
+if (rawArgs.includes("--help") || rawArgs.includes("-h")) {
+    console.log(USAGE);
+    process.exitCode = 0;
+    process.exit(0);
+}
 let config;
 try {
     const args = parseAuditArgs(rawArgs);
@@ -89,6 +109,13 @@ if (model.securitySummary.ran) {
         console.log(`  Full report: ${model.securitySummary.reportPaths.text}`);
     }
 }
+if (model.androidSecurity.summary.requested) {
+    const android = model.androidSecurity.summary;
+    console.log(`\nAndroid security validation: status=${android.status} applicable=${android.applicable ?? "n/a"} verdict=${android.verdict ?? "(unknown)"} checks=${android.totalChecks} confirmed=${android.confirmedFindingCount} mappedIssues=${android.mappedIssueCount} candidates=${android.candidateSummary.totalCount}`);
+    if (android.reportPaths.text) {
+        console.log(`  Full report: ${android.reportPaths.text}`);
+    }
+}
 console.log(`\nInventory: ${model.inventory.totalScannedFileCount} file(s) scanned, ${model.inventory.skippedFileCount} skipped`);
 console.log(`  source=${model.inventory.filesByCategory.source} tests=${model.inventory.filesByCategory.tests} docs=${model.inventory.filesByCategory.docs} package=${model.inventory.filesByCategory.package} config=${model.inventory.filesByCategory.config} scripts=${model.inventory.filesByCategory.scripts} ci=${model.inventory.filesByCategory.ci}`);
 console.log(`Source of truth: package=${model.sourceOfTruth.packageName ?? "(none)"}@${model.sourceOfTruth.packageVersion ?? "?"} readme=${model.sourceOfTruth.hasReadme} changelog=${model.sourceOfTruth.hasChangelog} ciWorkflows=${model.sourceOfTruth.ciWorkflowCount}`);

package/dist/scripts/security/validate.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import path from "node:path";
 import { runSecurityValidation } from "../../src/securityValidation/validate/runSecurityValidation.js";
 import { resolveValidationTarget, reportFilenamePrefix } from "../../src/securityValidation/validate/resolveTarget.js";
 import { buildSecurityReportFromSummary } from "../../src/securityValidation/report/buildSecurityReport.js";
@@ -15,18 +16,35 @@ import { writeAndroidReportFiles } from "../../src/mobile/android/report/writeAn
 const USAGE = "Usage: npm run security:validate -- [--target <path>] [--out <dir>] [--report-prefix <name>] " +
     "[--checks deps,package,static,cli-adversarial,fuzz,boundary,subprocess,secrets,network] " +
     "[--profile node-cli-package|local-tool|npm-package|android] [--format text,json] [--fail-on blocker|high|medium|low] " +
-    "[--android-gradle-operations wrapper-version,tasks,assemble-debug,unit-test-debug,lint-debug]\n" +
+    "[--android-gradle-operations wrapper-version,tasks,assemble-debug,unit-test-debug,lint-debug] " +
+    "[--android-external-tools semgrep,osv,android-lint,dependency-check] " +
+    "[--android-external-network deny|allow-requested]\n" +
     "\n" +
     "Android profile:\n" +
     "  --profile android performs static, read-only Android project detection, manifest parsing,\n" +
-    "  permission/exported-component/intent-filter/deep-link audits, and static Gradle metadata\n" +
-    "  extraction. Gradle is never executed by default.\n" +
+    "  permission/exported-component/intent-filter/deep-link audits, static Gradle metadata\n" +
+    "  extraction, and (as of v0.4.1 Batch 8) eleven internal advanced security checks (network\n" +
+    "  security config, backup/release configuration, hardcoded secrets, signing configuration,\n" +
+    "  WebView, FileProvider, sensitive storage/logging, clipboard, and Firebase/Google services).\n" +
+    "  Gradle and external tools are never executed by default.\n" +
     "  --android-gradle-operations explicitly opts into running ONLY the listed allowlisted Gradle\n" +
     "  operations (wrapper-version, tasks, assemble-debug, unit-test-debug, lint-debug) via the\n" +
     "  project's own Gradle wrapper. Arbitrary Gradle tasks cannot be passed. This option is only\n" +
     "  valid together with --profile android.\n" +
+    "  --android-external-tools explicitly opts into running ONLY the listed allowlisted optional\n" +
+    "  external security tools (semgrep, osv, android-lint, dependency-check). No arbitrary tool\n" +
+    "  names, commands, or arguments can be passed. This option is only valid together with\n" +
+    "  --profile android.\n" +
+    "  --android-external-network controls whether a requested tool may use network access.\n" +
+    "  Defaults to deny (osv is skipped unless supported offline data is available; semgrep,\n" +
+    "  android-lint, and dependency-check always run offline/no-update regardless of this flag).\n" +
+    "  allow-requested authorizes network only for an explicitly requested tool whose Batch 7\n" +
+    "  contract supports it (currently only osv). This option is only valid together with\n" +
+    "  --profile android.\n" +
     "  Example: npm run security:validate -- --target \"<android-project-path>\" --profile android\n" +
-    "  Example: npm run security:validate -- --target \"<android-project-path>\" --profile android --android-gradle-operations wrapper-version,tasks";
+    "  Example: npm run security:validate -- --target \"<android-project-path>\" --profile android --android-gradle-operations wrapper-version,tasks\n" +
+    "  Example: npm run security:validate -- --target \"<android-project-path>\" --profile android --android-external-tools semgrep,android-lint\n" +
+    "  Example: npm run security:validate -- --target \"<android-project-path>\" --profile android --android-external-tools osv --android-external-network allow-requested";
 // Parse CLI arguments from process.argv (after the node/tsx and script path).
 const rawArgs = process.argv.slice(2);
 const toolRoot = resolveToolRoot(import.meta.url);
@@ -99,13 +117,27 @@ if (config.profile === "android") {
     else {
         console.log(`Gradle ops : (none requested — static-only validation, zero Gradle process execution)`);
     }
+    // v0.4.1 Batch 8 — external tools remain explicit opt-in, mirroring Gradle
+    // operations exactly. "allow-requested" (the CLI-facing value) maps to the
+    // Batch 7 dispatcher's "allow-for-requested-tool" network policy value.
+    const externalNetworkPolicy = config.androidExternalNetworkPolicy === "allow-requested" ? "allow-for-requested-tool" : "deny";
+    if (config.androidExternalToolIds.length > 0) {
+        console.log(`External   : ${config.androidExternalToolIds.join(", ")} (explicitly requested — network policy: ${config.androidExternalNetworkPolicy})`);
+    }
+    else {
+        console.log(`External   : (none requested — zero external-tool process execution)`);
+    }
     console.log("");
+    const reportsDir = config.out;
     let result;
     try {
         result = await validateAndroidTarget({
             toolRoot,
             targetPath: args.target,
             requestedGradleOperationIds: config.androidGradleOperationIds,
+            requestedExternalToolIds: config.androidExternalToolIds,
+            externalNetworkPolicy: externalNetworkPolicy,
+            externalToolArtifactRoot: path.join(reportsDir, "external-tools"),
         });
     }
     catch (err) {
@@ -117,9 +149,10 @@ if (config.profile === "android") {
     const reportModel = toAndroidReportModel(result, {
         profile: config.profile,
         requestedGradleOperations: config.androidGradleOperationIds,
+        requestedExternalTools: config.androidExternalToolIds,
+        externalNetworkPolicy: config.androidExternalNetworkPolicy,
     });
     const textReport = renderAndroidTextReport(reportModel);
-    const reportsDir = config.out;
     const prefix = args.reportPrefix ??
         reportFilenamePrefix({
             isSelf: result.target.local.isSelf,

package/dist/src/audits/core/auditConfig.js

@@ -8,10 +8,19 @@ const FLAGS_WITH_VALUE = {
     "--fail-on": "failOn",
     "--out": "out",
 };
+// v0.4.2 Batch 3 -- presence-only flags (no following value consumed).
+const BOOLEAN_FLAGS = {
+    "--android": "android",
+};
 export function parseAuditArgs(argv) {
     const result = {};
     for (let i = 0; i < argv.length; i++) {
         const arg = argv[i];
+        const booleanKey = BOOLEAN_FLAGS[arg];
+        if (booleanKey) {
+            result[booleanKey] = true;
+            continue;
+        }
         const key = FLAGS_WITH_VALUE[arg];
         if (!key)
             continue;
@@ -28,6 +37,10 @@ export function normalizeAuditConfig(raw, toolRoot) {
     const formats = parseFormatOption(raw.format);
     const failOn = parseFailOnOption(raw.failOn);
     const out = raw.out !== undefined ? resolveOutDir(raw.out) : defaultOutDir(toolRoot, types.value);
+    const android = raw.android === true;
+    if (android && !types.value.includes("security")) {
+        throw new Error(`Invalid combination: --android requires --types to include "security" (e.g. --types security or --types code-rot,security).`);
+    }
     return {
         targetPathArg: raw.target,
         targetMode: raw.target === undefined ? "self" : "external",
@@ -46,7 +59,9 @@ export function normalizeAuditConfig(raw, toolRoot) {
             raw.include === undefined &&
             raw.format === undefined &&
             raw.failOn === undefined &&
-            raw.out === undefined,
+            raw.out === undefined &&
+            raw.android === undefined,
+        android,
     };
 }
 function splitAndNormalizeList(raw, flagName) {

package/dist/src/audits/core/auditRunner.js

@@ -6,7 +6,7 @@ import { collectSourceOfTruth } from "./sourceOfTruth.js";
 import { collectSourceFacts } from "./collectSourceFacts.js";
 import { collectPythonProjectMetadata } from "./pythonProjectMetadata.js";
 import { runSecurityAuditAdapter } from "../security/securityAuditAdapter.js";
-import { SECURITY_AUDIT_NOT_RUN_SUMMARY } from "../security/securityAuditTypes.js";
+import { ANDROID_AUDIT_NOT_REQUESTED_SUMMARY, SECURITY_AUDIT_NOT_RUN_SUMMARY, } from "../security/securityAuditTypes.js";
 export async function runAudit(options) {
     const { config, toolRoot } = options;
     const registry = options.registry ?? DEFAULT_AUDIT_REGISTRY;
@@ -49,10 +49,12 @@ export async function runAudit(options) {
     // code-rot detector issues (registry order) first, then security findings
     // (security-validation check-execution order).
     let securitySummary = SECURITY_AUDIT_NOT_RUN_SUMMARY;
+    let androidSummary = ANDROID_AUDIT_NOT_REQUESTED_SUMMARY;
     if (config.types.includes("security")) {
-        const securityAudit = await runSecurityAuditAdapter({ toolRoot, config });
+        const securityAudit = await runSecurityAuditAdapter({ toolRoot, config, android: config.android ? { enabled: true } : undefined }, options.securityDependencies);
         issues.push(...securityAudit.issues);
         securitySummary = securityAudit.summary;
+        androidSummary = securityAudit.android;
     }
     const issueCounts = countIssuesBySeverity(issues);
     const { exitCode, reason } = calculateAuditExitCode(issues, config.failOn);
@@ -64,6 +66,7 @@ export async function runAudit(options) {
             failOn: config.failOn,
             out: config.out,
             isDefaultRun: config.isDefaultRun,
+            android: config.android,
         },
         targetSummary: {
             rootPath: target.rootPath,
@@ -81,6 +84,7 @@ export async function runAudit(options) {
         sourceFacts,
         pythonProjectMetadata,
         securitySummary,
+        androidSummary,
         noDetectorsRegistered: selected.length === 0,
     };
 }

package/dist/src/audits/report/auditReportModel.js

@@ -166,6 +166,7 @@ export function buildAuditReportModel(result, opts) {
             failOn: result.configSummary.failOn,
             out: result.configSummary.out,
             isDefaultRun: result.configSummary.isDefaultRun,
+            android: result.configSummary.android,
         },
         summary: {
             totalIssues: issues.length,
@@ -191,6 +192,10 @@ export function buildAuditReportModel(result, opts) {
         sourceFacts: summarizeSourceFacts(result.sourceFacts),
         pythonProjectMetadata: result.pythonProjectMetadata,
         securitySummary: result.securitySummary,
+        androidSecurity: {
+            summary: result.androidSummary,
+            candidates: result.androidSummary.candidateSummary,
+        },
         detectors,
         issues,
         skippedDetectors: result.skippedDetectors,
@@ -252,5 +257,7 @@ function reconstructCommand(result) {
         parts.push("--format", cfg.formats.join(","));
     parts.push("--fail-on", cfg.failOn);
     parts.push("--out", cfg.out);
+    if (cfg.android)
+        parts.push("--android");
     return parts.join(" ");
 }

package/dist/src/audits/report/renderAuditJsonReport.js

@@ -21,6 +21,7 @@ export function renderAuditJsonReport(model) {
         sourceFacts: model.sourceFacts,
         pythonProjectMetadata: model.pythonProjectMetadata,
         securitySummary: model.securitySummary,
+        androidSecurity: model.androidSecurity,
         detectors: model.detectors,
         issues: model.issues,
         skippedDetectors: model.skippedDetectors,