From b1ea509947e63352e25f60400487eda2ff63b5e4 Mon Sep 17 00:00:00 2001 From: AartiKandpal <209811996+AartiKandpal@users.noreply.github.com> Date: Thu, 8 Oct 2026 21:06:55 +0530 Subject: [PATCH 1/3] docs: document CLI usage in docs/CLI.md (#512) --- docs/CLI.md | 99 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 99 insertions(+) create mode 100644 docs/CLI.md diff --git a/docs/CLI.md b/docs/CLI.md new file mode 100644 index 00000000..340dfa29 --- /dev/null +++ b/docs/CLI.md @@ -0,0 +1,99 @@ +# CLI Reference + +PRISM provides a command-line interface (`cli.py`) for headlessly running scans, inspecting modules, and managing scheduled watchlists. + +--- + +## `scan` + +Run security scans against targets (domains, IPs, emails, phones, or usernames). + +### Usage + +```bash +python cli.py scan [options] +``` + +### Options + +* `--json`: Output results as raw JSON. +* `--html`: Generate an HTML scan report. +* `--pdf`: Generate a PDF scan report. +* `--graphml`: Export target entity graph in GraphML format. +* `--gexf`: Export target entity graph in GEXF format. +* `-m, --modules`: Specify comma-separated modules to execute. Modules are validated against the target type. +* `--verbose`: Output detailed execution logs. +* `--quiet`: Suppress output except critical errors. + +### Example + +```bash +python cli.py scan example.com --json +``` + +### Exit Codes + +* `0`: Scan completed successfully with no issues. +* `1`: General runtime error or invalid parameters. +* `2`: Vulnerabilities detected above threshold. + +### Skipped Modules Behavior + +When a module requires an API key that is missing, it is skipped but still appears in the `--json` output with `status: skipped`: + +```json +{ + "module": "shodan", + "status": "skipped", + "reason": "Missing API key" +} +``` + +--- + +## `modules` + +List and query available OSINT modules. + +### Usage + +```bash +python cli.py modules [options] +``` + +### Options + +* `--type `: Print modules compatible with a target type (e.g., `domain`, `ip`, `email`, `phone`, `username`). + +### Example + +```bash +python cli.py modules --type domain +``` + +--- + +## `watchlist` + +Manage background targets for scheduled periodic re-scanning. + +### Usage + +```bash +python cli.py watchlist [options] +``` + +### Subcommands + +* `list`: Display current watched targets. +* `add `: Add a target to the scheduled watchlist. +* `rm `: Remove a target from the watchlist. +* `pause `: Temporarily pause scheduled scans. +* `resume `: Resume scheduled scans. + +### Example + +```bash +python cli.py watchlist add example.com +python cli.py watchlist list +``` From 4c8716e7002a6b53bbe92a9173fec565c1cdcba6 Mon Sep 17 00:00:00 2001 From: Aarti Kandpal <209811996+AartiKandpal@users.noreply.github.com> Date: Sat, 10 Oct 2026 12:19:22 +0530 Subject: [PATCH 2/3] Update CLI.md --- docs/CLI.md | 115 ++++++++++++++++++++++++---------------------------- 1 file changed, 54 insertions(+), 61 deletions(-) diff --git a/docs/CLI.md b/docs/CLI.md index 340dfa29..9de74d8d 100644 --- a/docs/CLI.md +++ b/docs/CLI.md @@ -12,88 +12,81 @@ Run security scans against targets (domains, IPs, emails, phones, or usernames). ```bash python cli.py scan [options] -``` +Options +--json: Output results as raw JSON. -### Options +--html: Generate an HTML scan report. -* `--json`: Output results as raw JSON. -* `--html`: Generate an HTML scan report. -* `--pdf`: Generate a PDF scan report. -* `--graphml`: Export target entity graph in GraphML format. -* `--gexf`: Export target entity graph in GEXF format. -* `-m, --modules`: Specify comma-separated modules to execute. Modules are validated against the target type. -* `--verbose`: Output detailed execution logs. -* `--quiet`: Suppress output except critical errors. +--pdf: Generate a PDF scan report. -### Example +--graphml: Export target entity graph in GraphML format. -```bash -python cli.py scan example.com --json -``` - -### Exit Codes - -* `0`: Scan completed successfully with no issues. -* `1`: General runtime error or invalid parameters. -* `2`: Vulnerabilities detected above threshold. +--gexf: Export target entity graph in GEXF format. -### Skipped Modules Behavior - -When a module requires an API key that is missing, it is skipped but still appears in the `--json` output with `status: skipped`: - -```json -{ - "module": "shodan", - "status": "skipped", - "reason": "Missing API key" -} -``` +-t, --type : Specify target type (auto-detected if omitted). ---- +-m, --modules: Specify comma-separated modules to execute. Modules are validated against the target type. -## `modules` +-v, --verbose: Output detailed execution logs. -List and query available OSINT modules. +-q, --quiet: Suppress output except critical errors. -### Usage +-o, --output : Write output to file(s). With more than one format flag, each file gets its own proper extension from the base name (e.g., -o out --json --html writes out.json and out.html). -```bash -python cli.py modules [options] -``` +Example +Bash +python cli.py scan example.com --json --html -o report +Exit Codes +0: Scan completed successfully. -### Options +1: General runtime/scan error or interrupted by Ctrl+C. -* `--type `: Print modules compatible with a target type (e.g., `domain`, `ip`, `email`, `phone`, `username`). +2: Unknown module name passed to -m (argparse also uses 2 for bad arguments). -### Example +Skipped Modules Behavior +When a module is skipped (e.g., missing API key), results are keyed by module name containing status, status_reason, and other fields: -```bash -python cli.py modules --type domain -``` +JSON +{ + "shodan": { + "status": "skipped", + "status_reason": "Missing API key", + "error": null + } +} +modules +List and query available OSINT modules. ---- +Usage +Bash +python cli.py modules [options] +Options +-t, --type : Print modules compatible with a target type (e.g., domain, ip, email, phone, username). -## `watchlist` +--json: Output available modules as raw JSON. +Example +Bash +python cli.py modules --type domain --json +watchlist Manage background targets for scheduled periodic re-scanning. -### Usage - -```bash +Usage +Bash python cli.py watchlist [options] -``` +Subcommands +list: Display current watched targets (--json supported). -### Subcommands +add : Add a target to the scheduled watchlist. Supports -t/--type, -m, --interval (hours, default 24), and --webhook. -* `list`: Display current watched targets. -* `add `: Add a target to the scheduled watchlist. -* `rm `: Remove a target from the watchlist. -* `pause `: Temporarily pause scheduled scans. -* `resume `: Resume scheduled scans. +rm : Remove a target from the watchlist by its entry ID. -### Example +pause : Temporarily pause scheduled scans by entry ID. + +resume : Resume scheduled scans by entry ID. + +Example +Bash +python cli.py watchlist add example.com --interval 12 --webhook [https://example.com/hook](https://example.com/hook) +python cli.py watchlist list --json -```bash -python cli.py watchlist add example.com -python cli.py watchlist list -``` From bac1f5bda2b9dd9f90a836ff1b4216f2e09edd66 Mon Sep 17 00:00:00 2001 From: Aarti Kandpal <209811996+AartiKandpal@users.noreply.github.com> Date: Sat, 10 Oct 2026 22:56:55 +0530 Subject: [PATCH 3/3] Update CLI.md --- docs/CLI.md | 92 +++++++++++++++++++++++++++++------------------------ 1 file changed, 51 insertions(+), 41 deletions(-) diff --git a/docs/CLI.md b/docs/CLI.md index 9de74d8d..c73dd651 100644 --- a/docs/CLI.md +++ b/docs/CLI.md @@ -12,41 +12,44 @@ Run security scans against targets (domains, IPs, emails, phones, or usernames). ```bash python cli.py scan [options] -Options ---json: Output results as raw JSON. +``` +### Options ---html: Generate an HTML scan report. +- `--json`: Output results as raw JSON. ---pdf: Generate a PDF scan report. +- `--html`: Generate an HTML scan report. ---graphml: Export target entity graph in GraphML format. +- `--pdf`: Generate a PDF scan report. ---gexf: Export target entity graph in GEXF format. +- `--graphml`: Export target entity graph in GraphML format. --t, --type : Specify target type (auto-detected if omitted). +- `--gexf`: Export target entity graph in GEXF format. --m, --modules: Specify comma-separated modules to execute. Modules are validated against the target type. +- `-t, --type `: Specify target type (auto-detected if omitted). --v, --verbose: Output detailed execution logs. +- `-m, --modules`: Specify comma-separated modules to execute. Modules are validated against the target type. --q, --quiet: Suppress output except critical errors. +- `-v, --verbose`: Output detailed execution logs. --o, --output : Write output to file(s). With more than one format flag, each file gets its own proper extension from the base name (e.g., -o out --json --html writes out.json and out.html). +- `-q, --quiet`: Suppress output except critical errors. -Example -Bash +- `-o, --output `: Write output to file(s). With more than one format flag, each file gets its own proper extension from the base name (e.g., `-o out --json --html` writes `out.json` and `out.html`). + +### Example +```bash python cli.py scan example.com --json --html -o report -Exit Codes -0: Scan completed successfully. +``` +### Exit Codes +- `0`: Scan completed successfully. -1: General runtime/scan error or interrupted by Ctrl+C. +- `1`: General runtime/scan error or interrupted by `Ctrl+C`. -2: Unknown module name passed to -m (argparse also uses 2 for bad arguments). +- `2`: Unknown module name passed to `-m` (argparse also uses `2` for bad arguments). -Skipped Modules Behavior -When a module is skipped (e.g., missing API key), results are keyed by module name containing status, status_reason, and other fields: +### Skipped Modules Behavior +When a module is skipped (e.g., missing API key), results are keyed by module name containing `status`, `status_reason`, and other fields: -JSON +```json { "shodan": { "status": "skipped", @@ -54,39 +57,46 @@ JSON "error": null } } -modules +``` +--- +## `modules` List and query available OSINT modules. -Usage -Bash +### Usage +```bash python cli.py modules [options] -Options --t, --type : Print modules compatible with a target type (e.g., domain, ip, email, phone, username). +``` +### Options +- `-t, --type `: Print modules compatible with a target type (e.g., `domain`, `ip`, `email`, `phone`, `username`). ---json: Output available modules as raw JSON. +- `--json`: Output available modules as raw JSON. -Example -Bash +### Example +```bash python cli.py modules --type domain --json -watchlist +``` +--- +## `watchlist` Manage background targets for scheduled periodic re-scanning. -Usage -Bash +### Usage + +```bash python cli.py watchlist [options] -Subcommands -list: Display current watched targets (--json supported). +``` +### Subcommands +- `list`: Display current watched targets (`--json` supported). -add : Add a target to the scheduled watchlist. Supports -t/--type, -m, --interval (hours, default 24), and --webhook. +- `add `: Add a target to the scheduled watchlist. Supports `-t/--type`, `-m`, `--interval` (hours, default 24), and `--webhook`. -rm : Remove a target from the watchlist by its entry ID. +- `rm `: Remove a target from the watchlist by its entry ID. -pause : Temporarily pause scheduled scans by entry ID. +- `pause `: Temporarily pause scheduled scans by entry ID. -resume : Resume scheduled scans by entry ID. +- `resume `: Resume scheduled scans by entry ID. -Example -Bash -python cli.py watchlist add example.com --interval 12 --webhook [https://example.com/hook](https://example.com/hook) +### Example +```bash +python cli.py watchlist add example.com --interval 12 --webhook https://example.com/hook python cli.py watchlist list --json - +```