Android-Pentesting-Skill

---
name: Android-Pentesting-Skill
description: >
license: Apache-2.0
---

# Android APK Security Audit

## Overview
Deterministic 6-phase static analysis + optional dynamic confirmation workflow. Remove noise early, keep the package scope tight. Only report vulnerabilities where source, propagation, and sink are understood or clearly marked as needing dynamic confirmation.

## When to Use
- User provides an APK file for security review
- User asks to analyze decompiled Android source code
- User needs to modify or repackage an APK for testing
- User wants mobile security testing or vulnerability assessment
- User needs help testing exported components, deep links, or intent injection
- User mentions Android reverse engineering or malware analysis

## Critical Rules
1. NEVER report bare grep hits without traced context
2. ALWAYS constrain searches to the app namespace (avoid library noise)
3. STOP and report immediately if decoding fails
4. ALWAYS use imperative language in findings
5. NEVER skip validation — if unsure, mark as "Needs Dynamic Confirmation"
6. ALWAYS provide concrete PoC (adb command, Frida hook, or malicious intent)
7. NEVER duplicate findings for the same root cause

> **Quality Note**: Take your time to analyze thoroughly. Quality is more important than speed. Do not skip validation steps — a false positive is worse than a missed finding.

## Execution Model
Tools to use: bash, write, edit, read, glob, grep for core workflow.

## Toolchain Requirements
Before starting, verify these tools are installed:
- **APKTool** 3.0.2+ (`apktool --version`) — aapt2-only mode; requires Java 17+
- **JADX** 1.5.5+ (`jadx --version`)
- **Android SDK Platform Tools 36.0.2** (`adb`, `fastboot`)
- **Android SDK Build Tools 36.0.0** (`apksigner`, `zipalign`, `aapt2`, `d8`)
- **Frida** 17.x (`frida --version`) — ⚠️ Frida-server on device must match the **frida core** version (the `frida` Python package), NOT frida-tools
- **Objection** 1.12.5+ (`objection --version`)
- **APKiD** 3.1.0+ (`apkid --version`)

Run `scripts/06-setup/preflight-check.sh` (bash), `scripts/06-setup/preflight-check.py` (universal, JSON output), or `scripts/06-setup/preflight-check.ps1` (PowerShell) to verify all tools. See `references/environment-setup.md` for installation instructions.

---

## AI-Powered Analysis

This skill includes AI-powered analysis capabilities. The AI model running this skill has built-in code analysis - use it strategically to enhance findings.

### When to Use AI
- Analyzing decompiled code for semantic vulnerabilities
- Tracing complex data flows (source-to-sink)
- Generating Proof-of-Concept exploits
- Filtering false positives from automated scans
- Understanding obfuscated code behavior
- Enhancing report quality and context

### How to Use AI
1. **Analyze specific code sections**: Don't ask AI to find ALL vulnerabilities - target specific suspicious code
2. **Provide context**: Include the full function/class, not just snippets
3. **Ask for CVSS scoring**: Request severity assessment with CVSS 4.0
4. **Verify findings**: Always validate AI findings against code and Frida testing

### AI Analysis Prompts
See `references/ai-pentesting-guide.md` for complete methodology and prompt templates.

Quick examples:
```
ANALYZE: Is this SQL injection exploitable?
Code: <vulnerable_query_with_user_input>
Context: <userId from Intent extra>

For each finding provide:
- CWE ID and CVSS 4.0 score
- Exploitation scenario
- Frida script to demonstrate (if applicable)
```

> **Reference**: `references/ai-pentesting-guide.md` - Complete AI analysis methodology

> **Inventory**: [`references/project-manifest.md`](references/project-manifest.md) is the ground-truth list of every packaged file and directory.

---

## Audit Mode Selection

Select the smallest mode that satisfies the user request. See `references/audit-modes.md` for full feature flags and presets.

| Mode | Default Use | Notes |
|------|-------------|-------|
| `quick` | First-pass triage | Decode, manifest, focused static checks, coverage statement. |
| `static` | No device/emulator | Static analysis only; mark runtime-only issues `Needs Dynamic Confirmation`. |
| `full` | Standard APK audit | Static + dynamic + MASVS + optional executive risk score. |
| `protected-app` | Packing/RASP blocks analysis | Follow protected-app fallback and record coverage gaps. |
| `osint` | Public exposure enrichment | Passive, in-scope OSINT only. |
| `reporting-only` | Existing findings JSON | Deduplicate, triage, MASVS, risk score, report. |

---

## Phase 0 — Decode and Detect Framework

### Decode APK
```bash
apktool d app.apk -o decoded/         # Decode resources + smali
jadx -d jadx_output app.apk           # Decompile to Java
apkid app.apk                         # Detect framework/packer
```

### Framework Detection
Identify the app's architecture early to tailor analysis.

**React Native**: `grep -r "com.facebook.react" decoded/AndroidManifest.xml` · Check for `libhermes.so` and `index.android.bundle` in assets/

**Flutter**: `grep -r "io.flutter" decoded/AndroidManifest.xml` · Check for `libflutter.so` and `assets/flutter_assets/`

**Cordova/Ionic**: `grep -r "org.apache.cordova" decoded/AndroidManifest.xml` · Check `assets/www/` for cordova.js

**Xamarin**: `grep -r "mono\|com.xamarin" decoded/AndroidManifest.xml` · Check for `libmonodroid.so`

> **Reference**: `references/hybrid-webview-frameworks.md` for complete detection scripts, Frida detection hooks, and framework-specific security considerations.

> **Cross-Platform Analysis Scripts**: Use `scripts/01-cross-platform/cordova-analysis.sh`, `scripts/01-cross-platform/flutter-analysis.sh`, `scripts/01-cross-platform/react-native-analysis.sh`, and `scripts/01-cross-platform/unity-analysis.sh` for framework-specific static analysis of Cordova/Ionic, Flutter, React Native, and Unity applications respectively. These scripts extract framework-specific metadata, identify native module usage, and highlight security considerations unique to each framework.

### Obfuscation Detection
- **ProGuard/R8**: Class names like `a.b.c`, `a$a`, `a$1`
- **DexGuard**: Additional string encryption and native methods
- **Custom obfuscation**: Unusual patterns, mixed naming schemes

> **Reference**: `references/static-analysis-patterns.md` for detailed detection patterns.

---

## Phase 1 — Attack Surface Mapping

### Analyze AndroidManifest.xml
```bash
cat decoded/AndroidManifest.xml
aapt2 dump badging app.apk
```

### Exported Components
Exported components are attack surfaces:

| Component | Exported If | Security Checks |
|-----------|-------------|-----------------|
| Activities | `android:exported="true"` | Intent filters, permission requirements |
| Services | `android:exported="true"` | Intent filters, permission requirements |
| Receivers | `android:exported="true"` | Intent filters, permission requirements |
| Providers | `android:exported="true"` | Path permissions, read/write permissions |

### Deep Link Schemes
Extract and document all deep link schemes:
```xml
<intent-filter>
    <data android:scheme="scheme" android:host="host" />
</intent-filter>
```

### Security-Relevant XML Resources
Check `res/xml/` for: `network_security_config.xml` (TLS/cleartext), file provider paths, preferences.

> **Reference**: `references/android-manifest-checklist.md` for complete 50+ manifest checks.
> **IPC / intent abuse**: see `references/intent-injection.md` and `references/pendingintent-security.md`.

---

## Phase 2 — Targeted Triage

### Scoped Grep Patterns
ALWAYS grep within the app namespace only. Use patterns from `references/static-analysis-patterns.md`:

| Category | Example Patterns | What to Look For |
|----------|------------------|------------------|
| WebView sinks | `loadUrl\(`, `evaluateJavascript` | Loading untrusted URLs |
| IPC sources | `getIntent()`, `onNewIntent()` | Unsanitized data entry |
| Intent relays | `getParcelableExtra`, `getSerializableExtra`, `startActivity\(`, `sendBroadcast\(` | Nested intent / confused deputy patterns |
| Hardcoded secrets | `password\s*=`, `api[_-]?key` | Credentials in code |
| Encoded literals | `Base64\.decode`, `"\x[0-9a-f]"` | Obfuscated strings |
| Weak crypto | `DES/`, `MD5`, `"AES/ECB"` | Insecure algorithms |
| Insecure storage | `SharedPreferences`, `MODE_WORLD_READABLE` | Unprotected data |
| Network/TLS | `TrustManager`, `X509TrustManager` | SSL validation bypass |
| Native bridges | `System\.loadLibrary`, JNI methods | Native code interfaces |

### Resource File Analysis
Check `res/values/strings.xml` for secrets:
```bash
grep -iE "(key|token|secret|password|api)" decoded/res/values/strings.xml
```

> **Reference**: `references/static-analysis-patterns.md` for 100+ grep patterns organized by vulnerability type.

### Phase 2.5 — Static Analysis Rules (Optional)

The semgrep-based static analysis module augments grep patterns with OWASP MASTG rules:

```bash
# Enable semgrep in auto-audit-static.sh
bash scripts/auto-audit-static.sh app.apk --semgrep

# Run semgrep scan standalone
python3 scripts/03-static-analysis/semgrep-scan.py decoded/ --output findings-semgrep.json

# Merge findings with existing findings
python3 scripts/03-static-analysis/merge-findings.py --input findings.json semgrep.json --output merged.json

# Update rules from upstream
bash scripts/03-static-analysis/update-rules.sh --fetch
```

**Features**:
- 70+ MASTG-aligned rules covering crypto, network, storage, authentication
- Non-blocking fallback (continues if semgrep is not available)
- Deduplication by CWE + title before merging
- Phase 2.5 runs after grep patterns, before data flow tracing

> **Reference**: `scripts/03-static-analysis/semgrep-scan.py --help` for rule categories and update workflow.

---

## Phase 3 — Data Flow Tracing

### Source-to-Sink Methodology
Map data flow from untrusted sources to dangerous sinks:

#### Common Sources

| Source | Method | Example |
|--------|--------|---------|
| IPC (Activities) | `getIntent()` | Malicious intent data |
| IPC (Services) | `onStartCommand()` | Start extras |
| Deep Links | `getIntent().getData()` | URL parameters |
| WebView | `JavascriptInterface` | Untrusted JS calls |
| Network | `HttpResponse` | API responses |
| Storage | `SharedPreferences` | Stored user input |
| External | `Environment.getExternalStorageDirectory()` | File system data |

#### Common Sinks

| Sink | Method | Impact |
|------|--------|--------|
| Command Execution | `Runtime.exec()`, `ProcessBuilder` | RCE |
| WebView Load | `loadUrl()`, `loadData()` | XSS, Phishing |
| File Operations | `FileWriter`, `FileOutputStream` | Path traversal, LFI |
| IPC Broadcast | `sendBroadcast()` | Intent injection |
| Reflection | `Class.forName()`, `getMethod()` | Code execution |
| Native Calls | JNI | Native code execution |
| SQL | `SQLiteDatabase.execSQL()` | SQL injection |

### Decision Rules

| Rule | Condition | Action |
|------|-----------|--------|
| 1 | Direct flow source → sink | Report as **Likely** |
| 2 | Indirect flow via static analysis | Report as **Likely** if path clear |
| 3 | Dynamic/reflective call | Mark as **Needs Dynamic Confirmation** |
| 4 | Native boundary | Mark as **Needs Dynamic Confirmation** |
| 5 | Library code | Verify if app wraps securely |
| 6 | No sanitization | Escalate severity |

### Manual Checks Grep Misses

| Check | Why grep misses | How to verify |
|-------|----------------|---------------|
| Runtime permissions | `requestPermissions()` calls | Trace `onRequestPermissionsResult` |
| Custom permission protections | `checkPermission()` | Look for permission checks |
| Activity transitions & intent relays | `startActivity()` hides nested-intent forwarding and grant flags | Follow intent construction, `Parcelable` relays, and `FLAG_GRANT_*` usage |
| File provider paths | XML + code | Map paths to exposed content URIs |
| Content provider queries | `query()` | Trace URI construction |

> **Reference**: `references/attack-patterns.md` for modern attack vectors: intent injection, deep link abuse, WebView universal XSS, task hijacking, file provider path traversal, broadcast theft, component hijacking.

---

## Phase 4 — Dynamic Analysis (Optional)

Use when static analysis hits a wall: obfuscation, reflection, native code, runtime protections.

### Runtime Defense Analysis (RDA)

The Runtime Defense Analysis module provides Frida-based detection and bypass for anti-analysis mechanisms:

```bash
# Run static audit first; RDA is a separate Phase 4 module
bash scripts/auto-audit-static.sh app.apk --semgrep

# Or via frida-exploit-helper.py
python3 scripts/07-tools/frida-exploit-helper.py -p com.target.app --runtime-defense

# List available detectors
bash scripts/02-rasp/runtime-defense-analyzer.sh --list

# Run with active bypass mode (attempt to bypass detections)
bash scripts/02-rasp/runtime-defense-analyzer.sh app.apk com.target.app --active-mode --authorized-lab
```

**Available detector catalog** (18 entries: 14 executable detectors + 4 not-applicable backend/cloud entries):
- `rootbeer` — RootBeer library detection
- `safetynet` — SafetyNet attestation
- `emulator` — Emulator detection
- `debug` — Debugger detection
- `frida-detect` — Frida detection
- `screenshot` — Screenshot prevention detection
- `screenrecorded` — Screen recording detection
- `talsec`, `approov`, `dexguard`, `appdome`, `doverunner`, `digitalai` — commercial RASP/shielding detection
- `contrast`, `imperva`, `dynatrace`, `accuknox` — cataloged as not-applicable for direct Android APK detection

**Output**: `findings-rda.json` with detector results

> **Reference**: `scripts/02-rasp/README.md` for detailed detector documentation.

### Authorized RASP Bypass Validation

After RDA detection, use the DRY bypass runner instead of duplicating Frida logic per detector:

```bash
# List reusable bypass profiles
bash scripts/02-rasp/rasp-bypass-runner.sh --list-profiles

# Build a reviewed command from detector names
bash scripts/02-rasp/rasp-bypass-runner.sh \
  --package com.target.app \
  --detectors rootbeer,frida_detect,talsec \
  --print-command

# Execute only in an authorized lab
bash scripts/02-rasp/rasp-bypass-runner.sh \
  --package com.target.app \
  --from-rda findings-rda.json \
  --run --authorized-lab
```

The single source of truth is `scripts/02-rasp/bypass-profiles.json`; the runner reuses scripts under `assets/frida-scripts/`. Do not copy bypass logic into detector files. See `references/rasp-bypass-workflow.md` for coverage, limits, and reporting requirements.


### Frida Integration

```bash
# Spawn app with hook
frida -U -f com.example.app -l script.js

# Attach to running process
frida -U com.example.app -l script.js
```

### Using frida-exploit-helper.py

The `frida-exploit-helper.py` script provides a convenient wrapper for Frida operations with bundled scripts and common patterns.

**When to use**: Prefer `frida-exploit-helper.py` over direct Frida CLI for:
- Bundled Frida scripts (SSL pinning bypass, root detection bypass, etc.)
- Quick memory operations (read, write, find base address)
- Discovering available scripts
- Simplified Frida workflow

**Examples with bundled scripts**:
```bash
# SSL pinning bypass
python3 scripts/07-tools/frida-exploit-helper.py -p com.target.app --script ssl-pinning-bypass

# Root detection bypass
python3 scripts/07-tools/frida-exploit-helper.py -p com.target.app --script root-detection-bypass

# List all available bundled scripts
python3 scripts/07-tools/frida-exploit-helper.py --list-scripts

# Display app memory layout (find base addresses)
python3 scripts/07-tools/frida-exploit-helper.py -p com.target.app --layout

# Hook specific functions (malloc, free, etc.)
python3 scripts/07-tools/frida-exploit-helper.py -p com.target.app --hook malloc,free

# Read memory at address
python3 scripts/07-tools/frida-exploit-helper.py -p com.target.app --read 0x12345678 64

# Write to memory address
python3 scripts/07-tools/frida-exploit-helper.py -p com.target.app --write 0x12345678 deadbeef
```

**Key flags**:
- `-p, --package` — Target package name (required for most operations)
- `--script` — Use bundled script name (use `--list-scripts` to see options) or path to a .js file
- `--spawn` / `-s` — Spawn a new process for the target package
- `--attach` / `-a` — Attach to a running process
- `--list-scripts` — Display all available bundled Frida scripts
- `--layout` — Show memory layout and base addresses
- `--hook` — Comma-separated list of functions to hook
- `--read ADDRESS SIZE` — Read memory at address (hex) with size in bytes
- `--write ADDRESS DATA` — Write data to address (hex). Data can be hex or string
- `--base <library>` — Get base address of specified module (requires library name)

> **Reference**: See `scripts/07-tools/frida-exploit-helper.py --help` for complete options and bundled script catalog.

> **Reference**: bundled Frida scripts in `assets/frida-scripts/`. See `references/frida-scripts-index.md` for the canonical catalog.
> **Focused runtime triage**: use `assets/frida-scripts/android-file-access-monitor.js` for filesystem/storage visibility, `assets/frida-scripts/jni-tracer.js` for JNI/native boundary discovery, and `assets/frida-scripts/ipc-abuse-helper.js` for passive IPC logging plus intentional provider/deep-link validation.

> **Script Maturity Levels**:
> - **STABLE** (with known scope): Production-ready within documented coverage. `ssl-pinning-bypass.js` covers core Java TLS/TrustManager paths (see its header for exact list — not a full universal OkHttp/WebView solution). `root-detection-bypass.js`, `biometric-bypass.js`, `network-interceptor.js`, etc. have broad but not infinite coverage.
> - **BETA**: Functional but incomplete — use with caution

### JNI Trace (Native Library Tracing)

For advanced JNI and native library analysis, use `jnitrace`:

```bash
# Install jnitrace
pip install jnitrace

# Trace all JNI functions in a native library (spawn mode)
jnitrace -l libnative-lib.so -m spawn com.target.app

# Trace with attach mode (attach to already-running app)
jnitrace -l libnative-lib.so -m attach com.target.app

# Trace only JNI methods matching a regex (include filter)
jnitrace -l libnative-lib.so -m spawn com.target.app \
  -i ".*decrypt.*|.*sign.*"

# Exclude noisy JNI methods
jnitrace -l libnative-lib.so -m spawn com.target.app \
  -e "GetStringUTFChars|ReleaseStringUTFChars"

# Hide JNIEnv/JavaVM struct calls to reduce noise
jnitrace -l libnative-lib.so -m spawn com.target.app \
  --ignore-env --ignore-vm

# Output trace to JSON file for later analysis
jnitrace -l libnative-lib.so -m spawn com.target.app \
  -o trace-output.json
```

**Programmatic usage** (via npm package):
```bash
npm install jnitrace-engine
```

Use `jnitrace` when:
- Analyzing custom JNI bindings
- Understanding native library behavior
- Debugging native crashes
- Tracing crypto operations in native code

> **Note**: `jnitrace` requires the app to be started with Frida spawn mode. For more details, see `references/native-analysis.md` and `jni-tracer.js` for an alternative Frida-based approach.

### Objection Commands

```bash
# Modern syntax (preferred): objection -n <package> start
objection -n com.example.app start

# Legacy syntax (deprecated but still works): objection -g <package> explore
objection -g com.example.app explore

# Enumerate components
android hooking list activities
android hooking list services
android hooking list receivers

# Bypass protections
android sslpinning disable

# Enumerate Android Keystore entries
android keystore list
```

### ADB Runtime Testing

```bash
# Test exported activity
adb shell am start -n com.example.app/.MainActivity -a android.intent.action.VIEW -d "scheme://host"

# Test exported receiver
adb shell am broadcast -a com.example.app.ACTION -e key "value"

# Monitor logs
adb logcat | grep com.example.app
```

> **SSL Pinning bypass**: `references/dynamic-analysis-setup.md` + `assets/frida-scripts/ssl-pinning-bypass.js`
> **Split APK / AAB runtime handling**: `references/dynamic-analysis-setup.md#9-split-apk--aab-runtime-handling` for `pm path`, `adb install-multiple`, and `bundletool` workflows.
> **RASP bypass**: `references/rasp-bypass.md` + `assets/frida-scripts/native-root-detection-probe.js` for anti-debug, anti-frida, emulator detection, and native root-check escalation.
> **Protected-app fallback**: `references/packer-modern-unpacking.md#protected-app-fallback-decision-tree` for runtime extraction, spawn-mode instrumentation, embedded instrumentation fallback, and static-only coverage handling.

---

## Phase 5 — Classification and Reporting

### Compliance Score (Optional)

Generate a MASVS v2 compliance score alongside CVSS findings:

```bash
# Generate MASVS compliance score
python3 scripts/05-scoring/calculate-score.py findings.json --json-output > score.json

# Generate full report with MASVS score
python3 scripts/07-tools/generate-report.py --input findings.json --masvs --output report.html

# Use custom MASVS mapping
python3 scripts/07-tools/generate-report.py --input findings.json --masvs --masvs-mapping scripts/05-scoring/masvs-mapping.json --output report.html
```

**Scoring methodology**:
- 24 MASVS v2 controls assessed
- Weighted deduction based on severity (Critical×10, High×5, Medium×2, Low×1)
- Final score: 0–100 with letter grade (A/B/C/D/F)

**Grade thresholds**:
- A: 90–100 (Excellent)
- B: 75–89 (Good)
- C: 60–74 (Acceptable)
- D: 40–59 (Poor)
- F: 0–39 (Critical)

> **References**: `scripts/05-scoring/README.md` and `references/masvs-scoring-model.md` for control definitions, mapping semantics, and not-tested handling.

### Executive Risk Score (Optional)

When generating an executive report, include an aggregate risk score only after deduplication and confidence triage. Use `references/risk-score-model.md` to keep this separate from CVSS and MASVS:

- CVSS = severity of individual vulnerabilities
- MASVS = control coverage/compliance posture
- Executive risk score = aggregate operational exposure and coverage gaps

Do not deduct score for rejected false positives. Treat unresolved protected code, missing splits, or skipped dynamic validation as coverage gaps rather than confirmed vulnerabilities.

### OSINT Enrichment (Optional)

If the engagement scope allows passive reconnaissance, enrich Phase 5 with `references/osint-apk-recon.md`:

1. Correlate package name, app label, first-party domains, endpoints, and redacted secret fingerprints.
2. Search passive public sources only unless active probing is explicitly authorized.
3. Classify domains as first-party, likely first-party, third-party SDK, or unknown before reporting.
4. Promote OSINT evidence only when it supports an in-scope app finding or public exposure claim.

### Confidence Levels

| Level | Definition | Example Evidence |
|-------|-----------|------------------|
| **Confirmed** | Full source-to-sink trace validated | Direct call chain from IPC source to `Runtime.exec()` with no sanitization |
| **Likely** | Strong evidence, minor gaps | Static trace clear but reflection obscures final sink |
| **Needs Dynamic Confirmation** | Static analysis inconclusive | Obfuscated code or native boundary requiring runtime verification |

### Severity
Use CVSS 4.0. See `references/cvss-scoring-guide.md` for complete methodology and severity mapping.

### Finding Template

```markdown
## [ID] - [Title]

**Confidence**: [Confirmed/Likely/Needs Dynamic Confirmation]
**Severity**: [Critical/High/Medium/Low] (CVSS: [X.X])
**CWE**: [CWE-ID]
**OWASP**: [OWASP Category]

### Description
[1-2 sentences explaining what the vulnerability is]

### Affected Components
- **File**: `path/to/file.java`
- **Method**: `methodName()`
- **Component**: `[Activity/Service/Receiver/Provider]` (if applicable)

### Attack Scenario
1. Attacker [action, e.g., sends malicious intent with crafted data]
2. App [processing step, e.g., extracts parameter without validation]
3. Data propagates through [call chain]
4. Reaches sink [dangerous operation]
5. Results in [impact, e.g., arbitrary command execution]

### Proof of Concept
```bash
adb shell am start -n com.example.app/.MainActivity \
  -a android.intent.action.VIEW \
  -d 'exploit://host/path?payload=cmd%7Ccat%20/data/data/com.example.app/databases/db'
```
Or provide Frida hook script for dynamic verification.

### Impact
- **Confidentiality**: [High/Medium/Low/None] — [explanation]
- **Integrity**: [High/Medium/Low/None] — [explanation]
- **Availability**: [High/Medium/Low/None] — [explanation]

### Remediation
```java
// Provide secure code example
Intent intent = getIntent();
if (intent != null && intent.getData() != null) {
    String input = intent.getData().getQueryParameter("path");
    if (isValidPath(input)) {
        loadUrl(input);
    } else {
        Log.w(TAG, "Invalid path detected");
    }
}
private boolean isValidPath(String path) {
    return path != null && !path.contains("..") &&
           path.matches("^/safe/\\w+\\.html$");
}
```

### CVSS 4.0 Calculation
[Show vector string and score breakdown]
```

### Coverage Statement
End your report with:

```
Coverage Analysis:
- Static Analysis: Complete (all decompiled sources analyzed)
- Dynamic Analysis: [Complete/Partial/Not Performed] (reason if partial)
- Scope: [com.example.app.* namespace only]
- Framework: [React Native/Flutter/Native/Standard]
- Obfuscation: [ProGuard/R8/DexGuard/Custom/None]

Limitations:
- [List any limitations, e.g., "Native code analysis requires additional tools"]
- [Any components that could not be analyzed]
- [Any findings requiring additional verification]

Total Findings: X (Critical: Y, High: Z, Medium: A, Low: B)
```

> **Reference**: `references/reporting-templates.md` for executive summary format, remediation priority matrix, and presentation templates.

### Automated Report Generation

Use the `generate-report.py` script to generate professional HTML or Markdown reports from findings JSON:

```bash
# Generate HTML report
python3 scripts/07-tools/generate-report.py \
  --input findings.json \
  --output report.html \
  --app-name "My App" \
  --package-name "com.example.app"

# Generate Markdown report
python3 scripts/07-tools/generate-report.py \
  --input findings.json \
  --output report.md \
  --app-name "My App" \
  --package-name "com.example.app"
```

The script supports both JSON array format and JSONL (one finding per line) and automatically:
- Sorts findings by severity (Critical first)
- Calculates CVSS 4.0 severity scores
- Generates executive summary with risk rating
- Maps OWASP MASTG categories
- Provides formatted proof of concept and remediation sections

See `scripts/test-findings.json` for the expected JSON structure.

---

## APK Modification Workflow

### 1. Decode
```bash
apktool d app.apk -o app-modified/
```

### 2. Modify — Smali Patching
Edit smali files in `app-modified/smali/`:
```smali
.method public checkSecurity()Z
    .locals 1
    # Original: iget-boolean v0, p0, Lcom/example/App;->securityEnabled:Z
    # Patched — always return true
    const/4 v0, 0x1
    return v0
.end method
```

#### Resource Modification
Edit XML or resource files in `app-modified/res/`:
```xml
<!-- Example: enable debug flag -->
<bool name="debug_mode">true</bool>
```

### 3. Rebuild
```bash
apktool b app-modified/ -o app-modified.apk
```

### 4. Sign
```bash
# Generate keystore (first time only)
keytool -genkeypair -v -keystore my-release-key.jks -alias androiddebugkey -keyalg RSA -keysize 2048 -validity 10000

# Align first
zipalign -v 4 app-modified.apk app-aligned.apk

# Sign (apksigner supports v1, v2, v3, v3.1 signatures)
# Verify keystore exists before signing
if [ ! -f "my-release-key.jks" ]; then
    echo "Error: Keystore not found. Create it with keytool first."
    exit 1
fi
# --ks-key-alias is required when the keystore contains multiple keys; recommended in all cases
apksigner sign \
  --ks my-release-key.jks \
  --ks-key-alias androiddebugkey \
  --ks-pass pass:myPassword \
  --key-pass pass:myPassword \
  --out app-signed.apk \
  app-aligned.apk

# Verify signature
apksigner verify --verbose app-signed.apk
```

### 5. Install and Verify
```bash
adb install -r app-signed.apk
```

> **Reference**: `references/dynamic-analysis-setup.md` for advanced repackaging, signature verification bypass, and ADB debugging. See `references/apk-modification-guide.md` for smali editing edge cases and troubleshooting.

---

## Troubleshooting

### APK Decoding Fails
```bash
apktool d -f app.apk -o decoded/         # Force mode (re-decodes even if output dir exists)
aapt2 dump badging app.apk                # Verify APK integrity
apkid app.apk                             # Detect packer/protector
```
> Note: Apktool 3.0+ removed the `-api`/`--api-level` flag. The API level is now auto-detected from the APK.
If packed → see `references/packing-unpacking.md` for unpacking techniques.

### JADX Shows Bad Code
```bash
jadx --show-bad-code -v app.apk           # Show code even with errors
jadx --decompilation-mode fallback app.apk
jadx-gui app.apk                          # GUI for manual inspection
```

### Frida Cannot Attach
```bash
adb shell ps -A | grep frida
adb shell getprop ro.product.cpu.abi
adb shell "su -c 'killall frida-server'"
adb shell "su -c '/data/local/tmp/frida-server -D &'"
```
> Full setup: `references/dynamic-analysis-setup.md`

### Obfuscated Code Unreadable
- Identify obfuscator: `apkid app.apk`
- Enable JADX deobfuscation: `jadx --deobf app.apk`
- See `references/static-analysis-patterns.md` → "Obfuscation Patterns"
- Switch to Phase 4 for runtime behavior

### When to Escalate to Dynamic Analysis
Static analysis reaches limits when: obfuscation unclear, reflection, JNI boundaries, anti-debug/root detection, SSL pinning. → Proceed to Phase 4 using `references/dynamic-analysis-setup.md`.

---

## Examples

### Example 1: Quick Assessment
`com.example.app.apk` → Decode → Framework detect → Manifest audit → Secrets grep → CVSS report

### Example 2: SSL Pinning Bypass
`frida -U -f com.target.app -l ssl-pinning-bypass.js` → See `references/rasp-bypass.md` if fails

### Example 3: APK Repackaging
Decode → Modify → Rebuild → Sign → Install (see `references/apk-modification-guide.md`)

---

## Agent Operating Contract

This contract defines what every audit must produce, when to advance, when to stop, and how to report findings.

### Required Audit Artifacts

For every APK audit, produce these artifacts:

| Artifact | Phase | Description |
|----------|-------|-------------|
| `scope.json` | -1 | Package name, target scope, authorization confirmation |
| `toolchain-report.json` | 0 | Tool versions, availability, preflight results |
| `app-profile.json` | 0 | Framework, obfuscation, architecture |
| `attack-surface.json` | 1 | Exported components, deep links, permissions |
| `findings.json` | 2-4 | All findings in standard schema |
| `evidence/` | 2-4 | Screenshots, logs, PoC commands |
| `coverage-matrix.json` | 5 | MASVS control coverage status |
| `final-report.html` | 5 | Executive summary + technical findings |

### Stop Conditions — STOP AND REPORT IMMEDIATELY

| Condition | Action |
|-----------|--------|
| APK decode fails | Report `DECODE_FAILURE` with error log |
| Package name cannot be determined | Report `SCOPE_UNCLEAR` and stop |
| Target namespace cannot be isolated | Report `SCOPE_TOO_BROAD` |
| Dynamic testing requested but no Frida/device | Mark findings `Needs Dynamic Confirmation` |
| Encrypted/packed APK blocks analysis | Report `PACKED_APK` with partial coverage |

### Finding States

| State | When to Use | CVSS Required |
|-------|-------------|---------------|
| **Confirmed** | Full source-to-sink trace validated | Yes |
| **Likely** | Strong evidence, minor gaps in trace | Yes |
| **Needs Dynamic Confirmation** | Static inconclusive (obfuscation, reflection, JNI) | TBD |
| **Informational** | Best practice violation, low risk | Optional |
| **Rejected** | Previously reported, confirmed false positive | N/A |

### APK Type Handling

| Type | Analysis Approach |
|------|------------------|
| **Standard APK** | Full 6-phase workflow |
| **Split APK / AAB** | Phase 0 → detect base vs dynamic features, pull/install full split set, analyze each split separately; see `dynamic-analysis-setup.md#9-split-apk--aab-runtime-handling` |
| **Packed/Protected** | Phase 0 → static baseline, runtime extraction/spawn-mode/embedded instrumentation fallback; if blocked → `PACKED_APK` report with coverage gap |
| **React Native** | Phase 0 → extract Hermes bytecode, use `scripts/01-cross-platform/react-native-analysis.sh` |
| **Flutter** | Phase 0 → Blutter analysis, native SSL hooks |
| **Xamarin** | Phase 0 → identify Mono runtime, analyze bundled assemblies |
| **Obfuscated** | Phase 2 → enhanced grep + Phase 4 dynamic if available |

### Evidence Standards

Every finding must have:
1. **File + line reference** (or Frida trace for dynamic)
2. **Evidence snippet** (relevant code/data)
3. **Attack scenario** (how attacker exploits)
4. **CVSS 4.0 vector** (Confirmed/Likely) or `TBD` (Needs Dynamic)

### Coverage Declaration

End every report with:

```json
{
  "coverage": {
    "static_analysis": "complete | partial | not-performed",
    "dynamic_analysis": "complete | partial | not-performed",
    "framework": "react-native | flutter | cordova | xamarin | native",
    "obfuscation": "proguard | dexguard | custom | none",
    "native_code": "analyzed | not-analyzed | not-applicable",
    "rasp": "detected | not-detected | not-tested"
  },
  "total_findings": { "critical": 0, "high": 0, "medium": 0, "low": 0 }
}
```

---

## References Index

| Phase | Files | Phase | Files |
|-------|-------|-------|-------|
| 0 | `environment-setup`, `opencode-tooling`, `static-analysis-patterns`, `hybrid-webview-frameworks`, `kotlin-patterns`, `kotlin-async-security`, `kotlin-compose-security`, `kotlin-multiplatform-security`, `malware-analysis`, `tool-installation` | 3 | `attack-patterns`, `intent-injection`, `pendingintent-security`, `firebase-security`, `deep-link-exploitation`, `real-world-android-vulnerabilities` |
| 1 | `android-manifest-checklist`, `android-version-security`, `android-14-15-security-changes`, `android-15-security-guide`, `android-16-security-guide`, `androidx-security-migration`, `secure-storage-migration` | 4 | `dynamic-analysis-setup`, `native-code-analysis`, `native-analysis`, `rasp-bypass`, `rasp-bypass-workflow`, `packing-unpacking`, `packer-modern-unpacking`, `react-native-hermes-analysis`, `frida-version-matching-guide`, `android-keystore2-testing`, `biometric-testing-comprehensive`, `frida-advanced-patterns`, `android-anti-frida-countermeasures` |
| 2 | `dependency-analysis`, `supply-chain-security` | 5 | `cvss-scoring-guide`, `cvss-calculator`, `reporting-templates`, `finding-template-cards`, `masvs-scoring-model`, `risk-score-model`, `osint-apk-recon`, `audit-modes`, `frida-scripts-index`, `cheat-sheet-commands`, `cheat-sheet-frida-scripts` |
| Mod | `apk-modification-guide`, `modern-android-coverage` | FW | `react-native-security`, `react-native-new-arch`, `flutter-security`, `flutter-blutter-analysis`, `jetpack-compose-security-deep-dive`, `fuzzing-guide`, `passkey-fido2-security`, `mobsf-integration` |
| CI | `automation-scripts`, `ci-cd-integration` | AI | `ai-pentesting-guide`, `ai-prompts/java-security-analyzer`, `ai-prompts/native-binary-analyzer`, `ai-prompts/exploit-generator`, `ai-prompts/report-enhancer` |
| Plat | `scripts/04-android-15-16/android15-apis.js`, `scripts/04-android-15-16/passkey-test.js`, `scripts/04-android-15-16/privacy-sandbox-test.sh` | Ker | `android-binder-cve-2023-20938` |
| All | `mastg-quick-reference`, `mastg-best-practices`, `mastg-privacy-testing`, `quick-commands`, `quick-start-guide`, `workflow-diagram`, `cross-platform-testing-setup`, `play-integrity-api-testing`, `burp-mobsf-integration-guide` |

**Scripts**:
- `scripts/01-cross-platform/` — Framework-specific analysis (Cordova, Flutter, React Native, Unity)
- `scripts/02-rasp/` — Runtime Defense Analysis (RDA)
- `scripts/03-static-analysis/` — semgrep scan + merge-findings
- `scripts/04-android-15-16/` — Android 15/16 specific APIs
- `scripts/05-scoring/` — MASVS v2 compliance scoring
- `scripts/06-setup/` — preflight-check + validation
- `scripts/07-tools/` — Core tools (frida-exploit-helper, generate-report, correlate-findings, mobsf-api-scan, burp-findings-export, rop-helper)
- `auto-audit-static.sh` — Main orchestrator
- `audit-android-components.sh` — Component audit
**Exploitation**: `exploitation-guide`, `heap-exploitation`, `exploitation-decisions`, `android-binder-cve-2023-20938`
**RASP bypass**: `scripts/02-rasp/rasp-bypass-runner.sh` uses `scripts/02-rasp/bypass-profiles.json` to compose reusable Frida bypass stacks. See `references/rasp-bypass-workflow.md`.
**Assets**: Frida scripts in `assets/frida-scripts/` (see `references/frida-scripts-index.md`); full file inventory is in [`references/project-manifest.md`](references/project-manifest.md)

> **Loading Strategy**: Load reference files only when encountering the specific technical challenge they cover. Do NOT load all references at once.

---

## Platform-Specific Notes

> See `references/environment-setup.md` for detailed Windows (PowerShell), macOS, and Linux setup. On macOS, use `rg` (ripgrep) instead of `grep -P` — BSD grep does not support PCRE.

## Known Implementation Gaps (as of remediation pass, April 2026)

The following gaps were identified and partially mitigated during a full code + claims audit:

- **Semgrep integration** (Phase 2.5): Previously completely non-functional (no `--json` flag was passed). Now fixed in `semgrep-scan.py`.
- **Preflight in agent contexts**: Interactive safety/scope prompts would hang or fail under `--json` / non-TTY. Now auto-skips with clear notes when run by agents/CI.
- **Frida bypass coverage claims**: Several "STABLE" / "30+ implementations" statements (especially `ssl-pinning-bypass.js`) were overstated vs. actual code. Script headers and key docs have been qualified; the script itself is now honest about scope.
- **Shell error handling**: Multiple blanket `&>/dev/null` and unquoted loops existed (especially in `audit-android-components.sh`). Critical decode path now uses `run_logged` helper with real log capture + timeouts. More work remains on other heavy-tool calls.
- **DRY / shared library**: `scripts/lib/` (findings schema, normalizers, MASVS helpers) was mostly dead code due to import hacks. Partial wiring started; full centralization of the 5–6 duplicated `load_findings` implementations is still pending.
- **Committed artifacts**: Many `__pycache__/` and `*.pyc` files were present. `.gitignore` has been expanded.

These are tracked in the remediation plan for this change. Always run the preflight + validators before trusting a full audit in a new environment.

> The skill prioritizes **honest, reproducible results over impressive-sounding claims**. When in doubt, mark "Needs Dynamic Confirmation" and surface coverage gaps explicitly.