From 70620fdb278abceea84446e3968a8f6dc48a2ca0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?FabioLeit=C3=A3o?= Date: Wed, 1 Jul 2026 07:31:11 -0300 Subject: [PATCH] docs(help): separate --demo from config-driven one-shot audits (#1121) Clarify that --demo uses a synthetic workspace under /tmp/data_boar_demo/ and ignores config.yaml in the CWD on /help, USAGE*, and man page. --- api/locales/en.json | 3 ++- api/locales/pt-BR.json | 3 ++- api/templates/help.html | 7 ++++--- docs/USAGE.md | 14 ++++++++++++++ docs/USAGE.pt_BR.md | 16 +++++++++++++++- docs/data_boar.1 | 33 ++++++++++++++++++++++---------- scripts/build_locale_catalogs.py | 14 ++++++++++++-- 7 files changed, 72 insertions(+), 18 deletions(-) diff --git a/api/locales/en.json b/api/locales/en.json index 49ea6e83..37b9852c 100644 --- a/api/locales/en.json +++ b/api/locales/en.json @@ -173,7 +173,8 @@ "run_auto_h3": "For automation / scripting", "run_cli_h3": "From the CLI", "run_cli_p1": "From the repo root, prefer uv run python main.py (or activate your venv and run python main.py). Full flag list: python main.py --help. Packaged installs: man 1 data-boar (command) and man 5 data-boar (config file format).", - "run_cli_oneshot": "One-shot audit (same targets as a dashboard scan):", + "run_cli_oneshot": "One-shot audit (config-driven; same targets as a dashboard scan with your config.yaml):", + "run_cli_demo": "Zero-config demo (synthetic config + corpus under /tmp/data_boar_demo/; ignores config.yaml in the CWD):", "run_cli_api": "Start the API / dashBOARd (no scan until you use the browser or HTTP):", "run_cli_tls": "You must either terminate TLS at the process (--https-cert-file + --https-key-file, or the same under api: in config) or explicitly accept plaintext with --allow-insecure-http (or api.allow_insecure_http: true). The official Docker image passes --allow-insecure-http by default; mount certs and remove it for HTTPS.", "run_cli_bind": "Bind order when using --web: --host overrides api.host in config and API_HOST; if none are set, the default is 127.0.0.1 (Docker image often sets API_HOST=0.0.0.0). Port: api.port in config vs --port. Transport: GET /status and GET /health include dashboard_transport — see docs/USAGE.md.", diff --git a/api/locales/pt-BR.json b/api/locales/pt-BR.json index e4afbf1c..e93deda7 100644 --- a/api/locales/pt-BR.json +++ b/api/locales/pt-BR.json @@ -173,7 +173,8 @@ "run_auto_h3": "Para automação / scripting", "run_cli_h3": "Pela CLI", "run_cli_p1": "Na raiz do repositório, prefira uv run python main.py (ou ative o venv e execute python main.py). Lista completa de flags: python main.py --help. Instalações empacotadas: man 1 data-boar (comando) e man 5 data-boar (formato do arquivo de configuração).", - "run_cli_oneshot": "Auditoria pontual (mesmos alvos que uma varredura pelo painel):", + "run_cli_oneshot": "Auditoria pontual (orientada ao config; mesmos alvos que uma varredura pelo painel com o seu config.yaml):", + "run_cli_demo": "Demonstração zero-config (config + corpus sintéticos em /tmp/data_boar_demo/; ignora o config.yaml do diretório atual):", "run_cli_api": "Subir a API / dashBOARd (sem varredura até usar o navegador ou HTTP):", "run_cli_tls": "É preciso terminar TLS no processo (--https-cert-file + --https-key-file, ou o mesmo em api: na config) ou aceitar explicitamente texto claro com --allow-insecure-http (ou api.allow_insecure_http: true). A imagem Docker oficial passa --allow-insecure-http por padrão; monte certificados e remova para HTTPS.", "run_cli_bind": "Ordem de bind com --web: --host sobrescreve api.host na config e API_HOST; se nada estiver definido, o padrão é 127.0.0.1 (a imagem Docker costuma definir API_HOST=0.0.0.0). Porta: api.port na config vs --port. Transporte: GET /status e GET /health incluem dashboard_transport — veja docs/USAGE.md.", diff --git a/api/templates/help.html b/api/templates/help.html index c8afec21..b4b6df11 100644 --- a/api/templates/help.html +++ b/api/templates/help.html @@ -33,10 +33,11 @@

{{ t('help.run_web_h3') }}

{{ t('help.run_auto_h3') }}

{{ t('help.run_cli_p1') }}

-

{{ t('help.run_cli_oneshot') }}

+

{{ t('help.run_cli_demo') }}

uv run python main.py --demo
-data-boar --demo
-uv run python main.py --config config.yaml
+data-boar --demo
+

{{ t('help.run_cli_oneshot') }}

+ 
uv run python main.py --config config.yaml
 uv run python main.py --config config.yaml --validate-config
 uv run python main.py --config config.yaml --diff <session_a> <session_b>
 uv run python main.py --config config.yaml --diff <session_a> <session_b> --fail-on-new-high
diff --git a/docs/USAGE.md b/docs/USAGE.md
index d6d4f8dc..a9e3813a 100644
--- a/docs/USAGE.md
+++ b/docs/USAGE.md
@@ -19,6 +19,7 @@ The main entry point is `main.py`.
 
 | Argument                | Default           | Description                                                                                                                                                                                                                                                                         |
 | ---                     | ---               | ---                                                                                                                                                                                                                                                                                 |
+| `--demo`                | *(flag)*          | **Zero-config demo:** creates a temp workspace under `/tmp/data_boar_demo/` (or the OS temp dir) with `demo.config.yaml`, a synthetic filesystem corpus, reports, and SQLite DB; runs an initial scan and starts the dashboard on loopback. **Ignores `config.yaml` in the current working directory.** Implies `--web` and `--allow-insecure-http`. Temp files are removed on exit. Incompatible with `--validate-config`, `--reset-data`, `--export-audit-trail`, `--export-dsar`, and `--diff`. |
 | `--config`              | `config.yaml`     | Path to the configuration file (YAML or JSON). Used for both one-shot audit and to resolve `api.port` / `api.host` when starting the web server.                                                                                                                                    |
 | `--web`                 | *(flag)*          | Start the REST API server instead of running a one-shot audit.                                                                                                                                                                                                                      |
 | `--port`                | `8088`            | Port for the API when `--web` is set. Can be overridden by `api.port` in config unless you pass `--port` explicitly. Ignored in one-shot mode.                                                                                                                                      |
@@ -53,6 +54,19 @@ Some enterprise deployments require explicit **tamper-evidence hooks** beside `l
 
 ### Outcomes
 
+## Zero-config demo (`--demo`)
+
+```bash
+data-boar --demo
+# or from a clone:
+uv run python main.py --demo
+```
+
+- **Not** a config-driven one-shot audit: `--demo` **does not** read `config.yaml` from the current working directory.
+- Prepares `/tmp/data_boar_demo/` (platform temp dir + `data_boar_demo/`) with `demo.config.yaml`, synthetic corpus, `reports/`, and `audit_results.db`, then runs an initial scan and keeps the dashboard on **`127.0.0.1`** with plaintext HTTP.
+- **Output:** Console banner with workspace path and dashboard URL (default port **8088**). Temp tree is removed when the process exits.
+- See also [QUICKSTART.md](../QUICKSTART.md) (*Caminho 0*) and `man 1 data-boar` (`--demo`).
+
 ## One-shot audit (no `--web`)
 
 ```bash
diff --git a/docs/USAGE.pt_BR.md b/docs/USAGE.pt_BR.md
index f223a510..27de3a9b 100644
--- a/docs/USAGE.pt_BR.md
+++ b/docs/USAGE.pt_BR.md
@@ -9,7 +9,7 @@ Esta página é o **guia de uso do operador**: **CLI**, **API web e dashboard**,
 O documento descreve, em português, como:
 
 - Executar a aplicação via **CLI** e **API web**;
-- Entender os parâmetros (`--config`, `--web`, `--port`, `--host`, `--https-cert-file`, `--https-key-file`, `--allow-insecure-http`, `--validate-config`, `--tenant`, `--technician`, `--scan-compressed`, `--content-type-check`, `--scan-stego`, `--jurisdiction-hint`);
+- Entender os parâmetros (`--demo`, `--config`, `--web`, `--port`, `--host`, `--https-cert-file`, `--https-key-file`, `--allow-insecure-http`, `--validate-config`, `--tenant`, `--technician`, `--scan-compressed`, `--content-type-check`, `--scan-stego`, `--jurisdiction-hint`);
 - Navegar pelo **dashboard web**;
 - Iniciar varreduras e baixar relatórios/heatmaps usando **curl**.
 
@@ -28,6 +28,7 @@ O ponto de entrada é `main.py`.
 
 | Argumento               | Padrão               | Descrição                                                                                                                                                                                                                                                                                |
 | ---                     | ---                  | ---                                                                                                                                                                                                                                                                                      |
+| `--demo`                | *(flag)*             | **Demonstração zero-config:** cria workspace temporário em `/tmp/data_boar_demo/` (ou diretório temp do SO) com `demo.config.yaml`, corpus sintético de filesystem, relatórios e SQLite; executa varredura inicial e sobe o dashboard em loopback. **Ignora o `config.yaml` do diretório atual.** Implica `--web` e `--allow-insecure-http`. Arquivos temporários são removidos ao sair. Incompatível com `--validate-config`, `--reset-data`, `--export-audit-trail`, `--export-dsar` e `--diff`. |
 | `--config`              | `config.yaml`        | Caminho do arquivo de configuração (YAML ou JSON). Usado em varredura única e para resolver `api.port` / `api.host` ao subir a API.                                                                                                                                                      |
 | `--web`                 | *(flag)*             | Inicia o servidor FastAPI em vez de executar uma varredura única.                                                                                                                                                                                                                        |
 | `--port`                | `8088`               | Porta da API quando `--web` é usado. Pode ser sobrescrita por `api.port` no config, salvo se você passar `--port` explicitamente. Ignorado em modo varredura única.                                                                                                                      |
@@ -62,6 +63,19 @@ Implantações corporativas podem exigir *hooks* de **tamper-evidence** paralelo
 
 ### Resultados
 
+#### Demonstração zero-config (`--demo`)
+
+```bash
+data-boar --demo
+# ou a partir do clone:
+uv run python main.py --demo
+```
+
+- **Não** é varredura pontual orientada ao seu config: `--demo` **não** lê o `config.yaml` do diretório atual.
+- Prepara `/tmp/data_boar_demo/` (temp do SO + `data_boar_demo/`) com `demo.config.yaml`, corpus sintético, `reports/` e `audit_results.db`, executa varredura inicial e mantém o dashboard em **`127.0.0.1`** com HTTP em texto plano.
+- **Saída:** banner no console com caminho do workspace e URL do dashboard (porta padrão **8088**). A árvore temporária é removida ao encerrar o processo.
+- Veja também [QUICKSTART.md](../QUICKSTART.md) (*Caminho 0*) e `man 1 data-boar` (`--demo`).
+
 #### Varredura única (sem `--web`)
 
 ```bash
diff --git a/docs/data_boar.1 b/docs/data_boar.1
index 3403c999..5063d59b 100644
--- a/docs/data_boar.1
+++ b/docs/data_boar.1
@@ -107,7 +107,17 @@ and
 .SH OPTIONS
 .TP
 .B \-\-demo
-Zero\-config demonstration mode: generate a synthetic filesystem corpus in a temporary directory, run an initial scan, and start the dashboard on loopback (\fB127.0.0.1\fR) with plaintext HTTP. Does not require
+Zero\-config demonstration mode: create a temp workspace under
+.IR /tmp/data_boar_demo/
+(or the OS temp directory) with
+.IR demo.config.yaml ,
+a synthetic filesystem corpus,
+.IR reports/ ,
+and SQLite DB; run an initial scan and start the dashboard on loopback (\fB127.0.0.1\fR) with plaintext HTTP.
+Does not read
+.B config.yaml
+from the current working directory.
+Does not require
 .BR \-\-config .
 Implies
 .BR \-\-web
@@ -559,7 +569,18 @@ The "Start scan" button triggers
 (a full audit of all targets in the current config).
 .
 .SH EXAMPLES
-.SS One\-shot CLI
+.SS Zero\-config demo
+.TP
+Synthetic corpus and dashboard (ignores
+.B config.yaml
+in the CWD):
+.RS
+.B data-boar \-\-demo
+.br
+.B python main.py \-\-demo
+.RE
+.
+.SS One\-shot CLI (config\-driven)
 .TP
 Minimal scan with default config:
 .RS
@@ -586,14 +607,6 @@ Without TLS certificate and key paths, you must pass
 in the configuration) for plaintext HTTP.
 .
 .TP
-Zero\-config demo (no configuration file):
-.RS
-.B data-boar \-\-demo
-.br
-.B python main.py \-\-demo
-.RE
-.
-.TP
 Start the API on port 8088 (plaintext, explicit opt\-in):
 .RS
 .B python main.py \-\-config config.yaml \-\-web \-\-allow\-insecure\-http \-\-port 8088
diff --git a/scripts/build_locale_catalogs.py b/scripts/build_locale_catalogs.py
index d019d6eb..c07bb0b5 100644
--- a/scripts/build_locale_catalogs.py
+++ b/scripts/build_locale_catalogs.py
@@ -205,7 +205,13 @@ def _en() -> dict:
                 "python main.py). Full flag list: python main.py --help. Packaged installs: "
                 "man 1 data-boar (command) and man 5 data-boar (config file format)."
             ),
-            "run_cli_oneshot": "One-shot audit (same targets as a dashboard scan):",
+            "run_cli_oneshot": (
+                "One-shot audit (config-driven; same targets as a dashboard scan with your config.yaml):"
+            ),
+            "run_cli_demo": (
+                "Zero-config demo (synthetic config + corpus under /tmp/data_boar_demo/; "
+                "ignores config.yaml in the CWD):"
+            ),
             "run_cli_api": "Start the API / dashBOARd (no scan until you use the browser or HTTP):",
             "run_cli_tls": (
                 "You must either terminate TLS at the process (--https-cert-file + --https-key-file, "
@@ -583,7 +589,11 @@ def tr(d: dict) -> dict:
         "man 1 data-boar (comando) e man 5 data-boar (formato do arquivo de configuração)."
     )
     base["help"]["run_cli_oneshot"] = (
-        "Auditoria pontual (mesmos alvos que uma varredura pelo painel):"
+        "Auditoria pontual (orientada ao config; mesmos alvos que uma varredura pelo painel com o seu config.yaml):"
+    )
+    base["help"]["run_cli_demo"] = (
+        "Demonstração zero-config (config + corpus sintéticos em /tmp/data_boar_demo/; "
+        "ignora o config.yaml do diretório atual):"
     )
     base["help"]["run_cli_api"] = (
         "Subir a API / dashBOARd (sem varredura até usar o navegador ou HTTP):"