## Sobre o Daksh SCRA

O Daksh SCRA (Source Code Review Assist) foi criado para aumentar a eficiência do processo de revisão de código-fonte, oferecendo uma abordagem bem estruturada e organizada para revisores de código.

Em vez de sinalizar indiscriminadamente tudo como um problema potencial, o Daksh SCRA promove uma análise criteriosa, incentivando a investigação e a confirmação de problemas potenciais. Essa abordagem reduz a correria de marcar cada preocupação potencial como um bug, diminuindo a confusão e o tempo desperdiçado com falsos positivos.

### Estreia

O Daksh SCRA foi inicialmente apresentado durante uma sessão de treinamento de revisão de código-fonte na Black Hat USA 2022 (6 a 9 de agosto), onde foi exibido de forma discreta para um público específico. Sua estreia pública oficial ocorreu na Black Hat USA 2023, em Las Vegas.

## Recursos e Funcionalidades

- **Identifica Áreas de Interesse no Código-Fonte:** Incentiva uma investigação e confirmação focadas, em vez de rotular indiscriminadamente tudo como um bug.
- **Identifica Áreas de Interesse em Caminhos de Arquivo (Primeiro do Mundo):** Reconhece padrões em caminhos de arquivo para apontar seções relevantes para revisão.
- **Reconhecimento em Nível de Software para Identificar Tecnologias Utilizadas:** Identifica as tecnologias do projeto, permitindo que revisores de código realizem varreduras precisas com regras adequadas.
- **Estimativa Científica Automatizada de Esforço para Revisão de Código (Primeiro do Mundo):** Oferece uma abordagem mensurável para estimar o esforço necessário para uma revisão de código.
- **Varredura Ciente de Frameworks:** Aplica automaticamente regras específicas de frameworks quando o framework do projeto é detectado.
- **Relatórios de Análise de Taint:** Relatórios HTML de fluxo de taint por plataforma, com temas de modo hacker e modo profissional.
- **RDL (Rule Description Language):** Lógica de regras externa referenciada com `rdl_ref` e executada pelo pipeline `core/rdl_engine.py` — suporta gates cientes de arquivos, expressões booleanas, observações do projeto e metadados de lógica exportados nos relatórios.
- **Estado da Varredura / Retomada:** Marca pontos de verificação em varreduras longas e retoma após interrupções.
- **Linha de Base de Supressão:** Gera e aplica uma linha de base de falsos positivos conhecidos para suprimi-los de relatórios futuros.
- **Interface Web:** Lançador de varreduras baseado em navegador, com feed de console em tempo real e navegador de artefatos de trabalhos.

> Aprimoramentos ativos estão em andamento. Vários novos recursos e melhorias estão planejados para os próximos lançamentos.

Sinta-se à vontade para contribuir com a atualização ou adição de novas regras e com o desenvolvimento futuro.

Se você encontrar algum bug, reporte-o para [[email protected]](mailto:[email protected]).

Documentação detalhada: [https://dakshlabs.com/#docs](https://dakshlabs.com/#docs)

---

## Primeiros Passos

Há duas maneiras de executar o Daksh SCRA — escolha a que melhor se adequa ao seu fluxo de trabalho:

| | Melhor para | Ir para |
|---|---|---|
| 🌐 **Interface Web (Docker)** | A maneira mais fácil de começar — um comando, um painel no navegador, progresso de varredura ao vivo e um navegador de relatórios/artefatos. Recomendado para a maioria dos usuários. | [Interface Web (Docker)](#web-ui-docker) |
| 💻 **CLI (Python)** | Scripts, pipelines de CI ou execução de varreduras sem Docker. | [Configuração da CLI](#cli-setup) |

Ambos os caminhos executam exatamente o mesmo mecanismo de varredura — a Interface Web é um front-end de navegador sobre a mesma CLI, portanto, os resultados são idênticos de qualquer forma.

---

## Interface Web (Docker)

A maneira mais rápida de executar o Daksh SCRA é por meio de sua Interface Web baseada em navegador, iniciada com um único comando do Docker Compose. Ela oferece um lançador de varreduras, um feed de console ao vivo e um histórico navegável de relatórios anteriores, sem precisar de um ambiente Python local.

A configuração do Docker executa a Interface Web e a CLI como serviços independentes criados a partir da mesma imagem, para que você possa usar um (ou ambos) a partir do mesmo contêiner.

### Iniciar a Interface Web

Modo em primeiro plano (os logs são transmitidos para o seu terminal):```bash
docker compose up --build

Em seguida, abra [http://localhost:8080](http://localhost:8080).

Para usar uma porta diferente:```bash
DAKSH_PORT=9090 docker compose up

### Iniciar sessão

A interface Web requer uma conta. No primeiro arranque, é criada uma conta de administrador inicial a partir de `DAKSH_ADMIN_USERNAME` / `DAKSH_ADMIN_PASSWORD` (defina estes valores em `.env`); se `DAKSH_ADMIN_PASSWORD` ficar por definir, é gerada uma palavra-passe aleatória e impressa uma única vez no registo de arranque da API - guarde-a, pois não pode ser recuperada posteriormente.

Será obrigado a definir a sua própria palavra-passe (e, opcionalmente, nome de utilizador) na primeira vez que iniciar sessão. Uma conta de administrador pode criar contas adicionais através do endpoint da API `POST /api/v1/auth/users` (ainda sem interface dedicada para isto). Consulte `.env.example` para a lista completa de definições relacionadas com autenticação (duração da sessão, segurança de cookies, CORS).

### O que obtém

- Construtor de comandos responsivo para os modos scan, recon, estimate, recon+estimate, list e PDF-from-JSON
- Feed de consola em tempo real e progresso por etapa ao vivo durante a execução
- Instantâneos de artefactos por tarefa para saídas HTML / PDF / JSON
- Navegação rápida no navegador entre o formulário de execução, feed ao vivo, artefactos e tarefas recentes
- Navegador de diretórios integrado para selecionar caminhos de destino (ciente do SO: Windows, macOS, Linux / Docker)

Nos bastidores, a CLI continua a ser a fonte de verdade - é ela que faz toda a análise e gera todas as saídas HTML / PDF / JSON. A interface Web executa uma tarefa ativa de cada vez e tira instantâneos das saídas de cada tarefa concluída para `runtime/webui/jobs/<job-id>/artifacts/`, para que relatórios anteriores permaneçam acessíveis.

### Executar a CLI no Docker

Também não precisa de um ambiente Python local para usar a CLI - está disponível como um serviço Compose próprio, construído a partir da mesma imagem:```bash
docker compose run --rm cli -h
docker compose run --rm cli -r auto -t /scan-targets/path/to/source

Ou descarregue o zip mais recente de [https://github.com/coffeeandsecurity/DakshSCRA](https://github.com/coffeeandsecurity/DakshSCRA) e descompacte-o.

### 2. Configurar um Ambiente Virtual

> 💡 O ambiente virtual pode ser criado em qualquer diretório - não precisa de estar dentro da pasta DakshSCRA.

**Opção A: Configuração num único passo (recomendada)**```bash
python setup_env.py

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

---

## Utilização da CLI

Use `python` dentro de um ambiente virtual, ou `python3` fora de um.

### Opções da Linha 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]

### Regras e Frameworks de Plataforma Suportados```bash
python dakshscra.py -l R    # List platform rules and framework mappings
python dakshscra.py -l RF   # List platform rules, framework mappings, and filetypes

---

## Referência de Configuração

### `config/tool.yaml`

Os padrões de tempo de execução do Daksh SCRA são controlados por meio 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

#### Sequência de digitalização

Para uma regra de origem, o DakshSCRA avalia a lógica nesta ordem:

1. O Recon seleciona plataformas e frameworks correspondentes.
2. A regra XML é carregada de `rules/scanning/platform/...`.
3. `regex` encontra linhas candidatas ou correspondências de arquivo inteiro quando presente.
4. `exclude` remove ruídos óbvios para essa regra, se presente.
5. O arquivo `.rdl` externo de `rdl_ref` é avaliado em relação ao texto do arquivo atual, ao caminho do arquivo atual e à raiz do projeto.
6. Se o script RDL passar, o DakshSCRA mantém a descoberta e mescla os metadados de lógica exportados na saída do relatório.
7. Se o script RDL falhar, a correspondência é suprimida com o motivo da falha do RDL e os metadados de rastreamento de decisão.

Para regras de caminho de arquivo em `filepaths.xml`, o mesmo modelo `rdl_ref` se aplica, mas o sujeito da correspondência é
o caminho relativo normalizado em vez do texto do código-fonte. Nesse modo, o RDL recebe a string do caminho relativo
como o texto do arquivo atual e o contexto do caminho.

#### Estrutura atual da regra```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>

#### Layout atual```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.

Os ficheiros de runtime (estado da análise, registos, inventário) são gravados em `runtime/`.

Ao executar através da interface Web, os resultados de cada tarefa são adicionalmente capturados em `runtime/webui/jobs/<job-id>/artifacts/` (consulte [Interface Web (Docker)](#web-ui-docker)).

---

## Autor

| | |
|---|---|
| Website | [coffeeandsecurity.com](https://www.coffeeandsecurity.com) |
| Email | [email protected] |
| Twitter / X | [@coffeensecurity](https://x.com/coffeensecurity) |
| Fonte | [github.com/coffeeandsecurity/DakshSCRA](https://github.com/coffeeandsecurity/DakshSCRA) |
| Licença | GNU General Public License v3.0 (GPL-3.0) |

Se o DakshSCRA ajudou a sua equipa a poupar tempo, esforço ou custos significativos, reduziu a dependência de ferramentas comerciais dispendiosas, melhorou a cobertura das revisões ou tornou a revisão de código mais estruturada e eficaz, não hesite em contactar e partilhar a sua experiência. Estou sempre aberto a feedback ponderado e conversas interessantes.

Encontrou um bug ou quer contribuir? Abra uma issue ou pull request no GitHub.