## Acerca de Daksh SCRA

Daksh SCRA (Source Code Review Assist) está diseñado para mejorar la eficiencia del proceso de revisión de código fuente, proporcionando un enfoque bien estructurado y organizado para los revisores de código.

En lugar de marcar indiscriminadamente todo como un posible problema, Daksh SCRA promueve un análisis reflexivo, instando a la investigación y confirmación de problemas potenciales. Este enfoque reduce la carrera por etiquetar cada posible preocupación como un error, recortando la confusión y el tiempo perdido en falsos positivos.

### Debut

Daksh SCRA se presentó inicialmente durante una sesión de formación sobre revisión de código fuente en Black Hat USA 2022 (6-9 de agosto), donde se mostró de forma discreta a un público específico. Su debut público oficial tuvo lugar en Black Hat USA 2023 en Las Vegas.

## Características y funcionalidades

- **Identifica áreas de interés en el código fuente:** Fomenta una investigación y confirmación centradas en lugar de etiquetar indiscriminadamente todo como un error.
- **Identifica áreas de interés en rutas de archivo (primicia mundial):** Reconoce patrones en las rutas de archivo para señalar secciones relevantes para la revisión.
- **Reconocimiento a nivel de software para identificar tecnologías utilizadas:** Identifica las tecnologías del proyecto, lo que permite a los revisores de código realizar escaneos precisos con reglas adecuadas.
- **Estimación científica automatizada del esfuerzo para la revisión de código (primicia mundial):** Proporciona un enfoque medible para estimar el esfuerzo requerido para una revisión de código.
- **Escaneo consciente del framework:** Aplica automáticamente reglas específicas del framework cuando se detecta el framework del proyecto.
- **Informes de análisis de taint:** Informes HTML de flujo de taint por plataforma con temas de modo hacker y modo profesional.
- **RDL (Rule Description Language):** Lógica de reglas externa referenciada con `rdl_ref` y ejecutada por el pipeline de `core/rdl_engine.py`: admite compuertas conscientes de archivos, expresiones booleanas, observaciones del proyecto y metadatos de lógica exportados en los informes.
- **Estado de escaneo / reanudación:** Marca escaneos largos y reanuda tras una interrupción.
- **Línea base de supresión:** Genera y aplica una línea base de falsos positivos conocidos para suprimirlos de futuros informes.
- **Interfaz web:** Lanzador de escaneos basado en navegador con feed de consola en tiempo real y navegador de artefactos de trabajos.

> Las mejoras activas están en curso. Se planean múltiples funciones y mejoras nuevas para próximas versiones.

Siéntete libre de contribuir a la actualización o adición de nuevas reglas y al desarrollo futuro.

Si encuentras algún error, repórtalo a [[email protected]](mailto:[email protected]).

Documentación detallada: [https://dakshlabs.com/#docs](https://dakshlabs.com/#docs)

---

## Primeros pasos

Hay dos formas de ejecutar Daksh SCRA: elige la que mejor se adapte a tu flujo de trabajo:

| | Mejor para | Ir a |
|---|---|---|
| 🌐 **Interfaz web (Docker)** | La forma más fácil de empezar: un solo comando, un panel en el navegador, progreso de escaneo en vivo y un navegador de informes/artefactos. Recomendado para la mayoría de los usuarios. | [Interfaz web (Docker)](#web-ui-docker) |
| 💻 **CLI (Python)** | Scripting, pipelines de CI o ejecución de escaneos sin Docker. | [Configuración CLI](#cli-setup) |

Ambas rutas ejecutan exactamente el mismo motor de escaneo: la interfaz web es un frontend de navegador sobre la misma CLI, por lo que los resultados son idénticos en ambos casos.

---

## Interfaz web (Docker)

La forma más rápida de ejecutar Daksh SCRA es a través de su interfaz web basada en navegador, lanzada con un solo comando de Docker Compose. Te ofrece un lanzador de escaneos, un feed de consola en vivo y un historial navegable de informes anteriores, sin necesidad de un entorno Python local.

La configuración de Docker ejecuta la interfaz web y la CLI como servicios independientes construidos a partir de la misma imagen, por lo que puedes usar cualquiera de los dos (o ambos) desde el mismo contenedor.

### Lanzar la interfaz web

Modo en primer plano (los registros se transmiten a tu terminal):```bash
docker compose up --build

Luego abre [http://localhost:8080](http://localhost:8080).

Para usar un puerto diferente:```bash
DAKSH_PORT=9090 docker compose up

### Iniciar sesión

La interfaz web requiere una cuenta. En el primer arranque, se crea una cuenta de administrador inicial a partir de `DAKSH_ADMIN_USERNAME` / `DAKSH_ADMIN_PASSWORD` (configúralas en `.env`); si `DAKSH_ADMIN_PASSWORD` se deja sin definir, se genera una contraseña aleatoria y se imprime una sola vez en el registro de inicio de la API: guárdala, ya que no se puede recuperar después.

Se te pedirá que establezcas tu propia contraseña (y, opcionalmente, nombre de usuario) la primera vez que inicies sesión. Una cuenta de administrador puede crear más cuentas mediante el endpoint de API `POST /api/v1/auth/users` (aún no hay una interfaz dedicada para esto). Consulta `.env.example` para ver la lista completa de ajustes relacionados con la autenticación (duración de la sesión, seguridad de cookies, CORS).

### Qué obtienes

- Constructor de comandos receptivo para los modos de escaneo, reconocimiento, estimación, reconocimiento+estimación, lista y PDF desde JSON
- Fuente de consola en tiempo real y progreso en vivo por etapa durante la ejecución
- Instantáneas de artefactos por trabajo para salidas HTML / PDF / JSON
- Navegación rápida en el navegador entre el formulario de ejecución, la fuente en vivo, los artefactos y los trabajos recientes
- Explorador de directorios integrado para seleccionar rutas de destino (consciente del sistema operativo: Windows, macOS, Linux / Docker)

Internamente, la CLI sigue siendo la fuente de verdad: realiza todo el escaneo y genera cada salida HTML / PDF / JSON. La interfaz web ejecuta un trabajo activo a la vez y guarda instantáneas de las salidas de cada trabajo completado en `runtime/webui/jobs/<job-id>/artifacts/` para que los informes anteriores sigan siendo accesibles.

### Ejecutar la CLI en Docker

Tampoco necesitas un entorno Python local para usar la CLI: está disponible como su propio servicio de Compose, construido a partir de la misma imagen:```bash
docker compose run --rm cli -h
docker compose run --rm cli -r auto -t /scan-targets/path/to/source

O descarga el último zip desde [https://github.com/coffeeandsecurity/DakshSCRA](https://github.com/coffeeandsecurity/DakshSCRA) y descomprímelo.

### 2. Configurar un Entorno Virtual

> 💡 El entorno virtual se puede crear en cualquier directorio: no es necesario que esté dentro de la carpeta DakshSCRA.

**Opción A: Configuración en un solo paso (recomendada)**```bash
python setup_env.py

macOS / Linux:```bash
python3 -m venv daksh-env
source daksh-env/bin/activate

---

## Uso de la CLI

Usa `python` dentro de un entorno virtual, o `python3` fuera de uno.

### Opciones de la línea de comandos```
usage: dakshscra.py [-h] [-r RULES] [-f FILE_TYPES] [-v] [-t TARGET_DIR]
                    [-l {R,RF}] [--recon] [--rs] [--estimate]
                    [-rpt FORMATS] [--pdf-from-json]
                    [--json-input-dir PATH] [--pdf-output PATH]
                    [--pdf-multi-dir PATH] [--pdf-single-only]
                    [--skip-analysis] [--loc]
                    [--baseline-file PATH] [--baseline-generate] [--no-baseline]
                    [--review-config PATH]
                    [--resume-scan] [--state-file PATH] [--no-state] [--state]

### Reglas y Frameworks de Plataforma Compatibles```bash
python dakshscra.py -l R    # List platform rules and framework mappings
python dakshscra.py -l RF   # List platform rules, framework mappings, and filetypes

---

## Referencia de Configuración

### `config/tool.yaml`

Los valores predeterminados del tiempo de ejecución de Daksh SCRA se controlan a través de `config/tool.yaml`.```yaml
state_management:
  enabled: false
  resume_mode: manual
  persist_after_seconds: 300
  persist_interval_seconds: 30
  default_state_file: runtime/scan_state.json
  cleanup_on_success: false

analysis:
  run_by_default: true
  include_frameworks: true
  report_theme: hacker_mode

#### Secuencia de escaneo

Para una regla de origen, DakshSCRA evalúa la lógica en este orden:

1. Recon selecciona las plataformas y frameworks coincidentes.
2. La regla XML se carga desde `rules/scanning/platform/...`.
3. `regex` encuentra líneas candidatas o coincidencias de archivo completo cuando están presentes.
4. `exclude` elimina el ruido obvio para esa regla, si está presente.
5. El archivo `.rdl` externo de `rdl_ref` se evalúa contra el texto del archivo actual, la ruta del archivo actual y la raíz del proyecto.
6. Si el script RDL pasa, DakshSCRA conserva el hallazgo y fusiona los metadatos de lógica exportados en la salida del informe.
7. Si el script RDL falla, la coincidencia se suprime con el motivo de fallo de RDL y los metadatos de seguimiento de decisión.

Para las reglas de ruta de archivo en `filepaths.xml`, se aplica el mismo modelo `rdl_ref`, pero el sujeto de coincidencia es
la ruta relativa normalizada en lugar del texto del código fuente. En ese modo, RDL recibe la cadena de ruta relativa
como el texto del archivo actual y el contexto de ruta.

#### Estructura de regla actual```xml
<rule>
  <name>Rule Name</name>
  <regex><![CDATA[regex_to_match]]></regex>
  <rdl_ref>logic/common/core/insecure_sql_query_unsafe_string_concatenation.rdl</rdl_ref>
  <exclude><![CDATA[pattern_to_exclude_lines]]></exclude>  <!-- optional -->
  <scan_config>...</scan_config>                           <!-- optional -->
  <rule_desc>Short description of what the rule detects.</rule_desc>
  <vuln_desc>Why the pattern matters.</vuln_desc>
  <developer>Fix guidance for developers.</developer>
  <reviewer>Manual confirmation guidance for reviewers.</reviewer>
</rule>

#### Diseño actual```text
rules/
└── scanning/
    ├── platform/
    │   ├── php/php.xml
    │   ├── java/java.xml
    │   └── ...
    └── logic/
        ├── common/core/
        ├── php/core/
        ├── php/framework/laravel/
        ├── mobile/android/core/
        ├── filepaths/core/
        └── ...

External RDL:```text
VERSION 1
WHEN PRESENT /\b(?:mysql_query|mysqli_query|->query)\s*\(/i
WHEN EXPR PRESENT:\$_(GET|POST|REQUEST|COOKIE) && MISSING:\b(?:prepare|bindParam|bindValue|PDO::prepare)\b
REPORT AS area_of_interest
REASON Query execution appears to rely on direct input without parameterisation.
FAIL_REASON Query API matched, but parameterised query indicators were also found in the file.

External RDL:```text
VERSION 1
WHEN FILE_NAME_IS AndroidManifest.xml
WHEN CURRENT_FILE_MATCHES /android:exported\s*=\s*"true"/i
WHEN MISSING /android:permission\s*=\s*"/i
REPORT AS area_of_interest
REASON Exported component appears reachable without a permission guard.

External RDL:```text
VERSION 1
WHEN CURRENT_FILE_MATCHES /(^|\/)(admin|administrator|root)(\/|$)/i
UNLESS CURRENT_FILE_MATCHES /(^|\/)(tests?|docs?|samples?|examples?)(\/|$)/i
REPORT AS area_of_interest
REASON File path suggests privileged application functionality.
FAIL_REASON Path matched an excluded documentation or sample location.

Los archivos de ejecución (estado del escaneo, registros, inventario) se escriben en `runtime/`.

Cuando se ejecuta a través de la interfaz web, las salidas de cada trabajo también se guardan como instantáneas en `runtime/webui/jobs/<job-id>/artifacts/` (consulte [Interfaz web (Docker)](#web-ui-docker)).

---

## Autor

| | |
|---|---|
| Sitio web | [coffeeandsecurity.com](https://www.coffeeandsecurity.com) |
| Correo electrónico | [email protected] |
| Twitter / X | [@coffeensecurity](https://x.com/coffeensecurity) |
| Fuente | [github.com/coffeeandsecurity/DakshSCRA](https://github.com/coffeeandsecurity/DakshSCRA) |
| Licencia | GNU General Public License v3.0 (GPL-3.0) |

Si DakshSCRA ha ayudado a tu equipo a ahorrar tiempo, esfuerzo o costes significativos, ha reducido la dependencia de herramientas comerciales caras, ha mejorado la cobertura de las revisiones o ha hecho que la revisión de código sea más estructurada y eficaz, no dudes en ponerte en contacto y compartir tu experiencia. Siempre estoy abierto a comentarios reflexivos y conversaciones interesantes.

¿Has encontrado un error o quieres contribuir? Abre un issue o pull request en GitHub.