# android-security-mcp

Servidor **MCP** (Model Context Protocol) para **auditoría de seguridad de apps Android**, pensado como herramienta de aprendizaje de hacking ético y análisis de aplicaciones. Combina tres fuentes:

- **ADB** → inventario de apps, permisos, extracción de APK y desinstalación.
- **VirusTotal** → reputación de malware por hash contra 70+ motores antivirus.
- **MobSF** → análisis estático de vulnerabilidades (OWASP Mobile Top 10).

> ⚠️ **Importante (alcance honesto):** esto es un **auditor**, no un antivirus en tiempo real. Android aísla cada app en su sandbox, así que ninguna herramienta aquí "limpia" el dispositivo sola. El flujo es: extraer → analizar → **recomendar**. Las acciones destructivas (desinstalar) siempre pasan por confirmación humana. Úsalo solo sobre dispositivos y apps que controles o tengas autorización para auditar.

---

## Arquitectura

```
android-security-mcp/
├── src/
│   ├── index.ts                 # entrada, servidor MCP + stdio
│   ├── config.ts                # carga de .env y guard de paquetes/confirmación
│   ├── schemas/
│   │   └── index.ts             # esquemas Zod centralizados (raw shapes)
│   ├── lib/
│   │   ├── exec.ts              # ejecución de comandos sin shell (anti-inyección)
│   │   ├── adb.ts               # wrapper de ADB
│   │   ├── hash.ts              # SHA-256 por streaming
│   │   ├── virustotal.ts        # cliente API VirusTotal v3
│   │   ├── mobsf.ts             # cliente REST de MobSF
│   │   └── result.ts            # helpers de respuesta MCP
│   └── tools/
│       ├── index.ts             # registerAllTools(server)
│       ├── deviceTools.ts       # inventario y permisos (lectura)
│       ├── extractTools.ts      # extracción de APK y hashing
│       ├── virustotalTools.ts   # reputación de malware
│       ├── mobsfTools.ts        # análisis de vulnerabilidades
│       ├── auditTools.ts        # flujo de auditoría consolidado
│       └── actionTools.ts       # acciones destructivas (con guard)
├── .env.example
├── tsconfig.json
└── package.json
```

Sigue el patrón modular `registerXxxTools(server)` con esquemas Zod centralizados y `exactOptionalPropertyTypes: true`.

---

## Requisitos previos

1. **Node.js ≥ 18.17** (usa `fetch`, `FormData` y `Blob` nativos).
2. **platform-tools (adb)** instalado y en el PATH, o ruta en `ADB_PATH`.
3. Dispositivo con **Depuración USB** activada y autorizada (`adb devices` debe verlo).
4. **API key de VirusTotal** (gratuita): https://www.virustotal.com/gui/my-apikey
5. **MobSF** corriendo en local con Docker:

```bash
docker pull opensecurity/mobile-security-framework-mobsf:latest
docker run -it --rm -p 8000:8000 opensecurity/mobile-security-framework-mobsf:latest
# usuario/clave por defecto: mobsf/mobsf — la API key aparece en la consola
```

---

## Instalación

```bash
npm install
cp .env.example .env   # y rellena tus claves
npm run build
```

Para desarrollo con recarga: `npm run dev`.

---

## Configuración (.env)

| Variable | Descripción | Default |
|---|---|---|
| `ADB_PATH` | Ruta al ejecutable de adb | `adb` |
| `ADB_SERIAL` | Serial del dispositivo (si hay varios) | _(vacío)_ |
| `REQUIRE_CONFIRM` | Exige `confirm=true` en acciones destructivas | `true` |
| `ALLOWED_PACKAGES_PREFIX` | Prefijos de paquete permitidos (CSV). Vacío = todos | _(vacío)_ |
| `WORK_DIR` | Carpeta donde se extraen los APK | `./work` |
| `VT_API_KEY` | API key de VirusTotal | _(vacío)_ |
| `MOBSF_URL` | URL de la instancia MobSF | `http://localhost:8000` |
| `MOBSF_API_KEY` | API key de MobSF | _(vacío)_ |

---

## Registro en Claude Code

En tu configuración de MCP (Windows), apunta al build:

```json
{
  "mcpServers": {
    "android-security": {
      "command": "node",
      "args": ["C:\\Users\\mstiv\\proyectos\\android-security-mcp\\dist\\index.js"],
      "env": {
        "ADB_PATH": "C:\\Users\\mstiv\\AppData\\Local\\Android\\Sdk\\platform-tools\\adb.exe",
        "VT_API_KEY": "tu_api_key",
        "MOBSF_API_KEY": "tu_api_key",
        "REQUIRE_CONFIRM": "true"
      }
    }
  }
}
```

---

## Herramientas disponibles

| Herramienta | Tipo | Qué hace |
|---|---|---|
| `adb_list_devices` | lectura | Lista dispositivos conectados |
| `adb_device_info` | lectura | Modelo, Android, SDK, parche de seguridad |
| `adb_list_packages` | lectura | Lista apps (por defecto solo de usuario) |
| `adb_package_permissions` | lectura | Permisos solicitados/concedidos y peligrosos |
| `apk_pull` | lectura | Extrae el APK base y calcula su SHA-256 |
| `apk_hash` | lectura | SHA-256 de un APK ya en disco |
| `vt_file_report` | lectura | Reputación en VirusTotal por hash |
| `vt_upload_file` | escritura | Sube un APK a VirusTotal si el hash no existe |
| `mobsf_upload` | escritura | Sube un APK a MobSF |
| `mobsf_scan` | escritura | Lanza análisis estático |
| `mobsf_scorecard` | lectura | Resumen de seguridad del análisis |
| `mobsf_report` | lectura | Informe JSON completo |
| `mobsf_delete_scan` | destructiva | Borra un análisis de MobSF |
| `audit_package` | lectura | **Flujo completo**: extrae + permisos + VT + MobSF + recomendación |
| `adb_uninstall_package` | **destructiva** | Desinstala una app (requiere `confirm=true`) |

---

## Flujo típico de uso

1. `adb_list_devices` → confirma que el dispositivo está conectado.
2. `adb_list_packages` → ve qué apps de usuario hay instaladas.
3. `audit_package { packageName: "com.ejemplo.sospechosa" }` → informe consolidado.
4. Si el informe recomienda actuar: `adb_uninstall_package { packageName, confirm: true }`.

---

## Notas de seguridad

- La ejecución de comandos usa `execFile` (sin shell) para evitar inyección.
- `ALLOWED_PACKAGES_PREFIX` limita el radio de acción a paquetes concretos.
- `REQUIRE_CONFIRM=true` evita que el agente desinstale apps por error o por un prompt injection.
- **Términos de VirusTotal:** la API pública no puede usarse como sustituto comercial de un antivirus. Esto es para auditoría/aprendizaje, no para distribuir como producto antivirus.

## Próximos pasos sugeridos

- Persistir informes de auditoría en disco/JSON para comparar versiones de una misma app.
- Añadir reglas **YARA** propias sobre el APK extraído.
- Integrar `mobsfscan` para análisis de código fuente en tus propios proyectos.

## Licencia

MIT