jxscout-findings

jxscout Findings

Findings are how you document security-relevant discoveries in a jxscout project. They persist in the project database and are visible across tools.

What deserves a finding

Create findings for things that have real security value:

• Confirmed vulnerabilities (XSS, IDOR, SSRF, open redirect, etc.)
• Interesting gadgets or primitives that could be chained into exploits (JSONP endpoints, postMessage handlers without origin checks, DOM clobbering gadgets, controllable redirect parameters)
• Security-relevant misconfigurations (missing CORS restrictions, overly permissive CSP, exposed debug endpoints)
• Sensitive data exposure (hardcoded secrets, API keys, internal URLs)

The bar is: would a security researcher find this useful? Not just full exploits -- useful building blocks count too.

What to avoid: purely theoretical risks with no supporting evidence. "This file uses eval()" is not a finding unless you can show how user input reaches it. Generic observations without context on exploitability or reachability are noise.

Prerequisites

The JXSCOUT_PROJECT_NAME environment variable must be set. All commands use jxscout-pro-v2 -c (client mode).

Commands

Create a finding

jxscout-pro-v2 -c create-finding \
  --kind <kind> \
  --severity <low|medium|high|critical> \
  --description "What was found, where, and why it matters" \
  --dedup-key <unique_key> \
  --metadata '{"key": "value"}'

Required:

• --kind -- finding category. Use descriptive, specific kinds: xss, idor, ssrf, open-redirect, postmessage-sink, gadget, secret-exposure, missing-origin-check, dom-clobbering, etc.
• --severity -- one of low, medium, high, critical

Optional:

• --description -- concise explanation of what was found, where, and why it matters
• --dedup-key -- prevents duplicate findings. If a finding with the same kind and dedup key already exists, the command returns a dedup message instead of creating a duplicate. Use a stable identifier (e.g. the endpoint path, the file + line, or a hash of the pattern).
• --metadata -- arbitrary JSON for structured data (e.g. affected endpoints, parameter names, payload used)

Returns JSON:

{"success": true, "finding_id": 42, "message": "Finding created with ID: 42"}

Or if deduplicated:

{"success": false, "finding_id": null, "message": "Finding was deduplicated (already exists)"}

List findings

jxscout-pro-v2 -c get-findings [options]

Options (all optional):

• --severity <value> -- filter by severity (repeatable): low, medium, high, critical
• --kind <value> -- filter by finding kind (repeatable)
• --limit <n> -- maximum number of findings to return
• --offset <n> -- number of findings to skip (for pagination)

Returns JSON with the matching findings and total count:

{"findings": [{"id": 1, "severity": "high", "kind": "xss", "description": "...", "dedup_key": "...", "metadata": {...}, "found_at": "2026-02-28T12:00:00"}], "total": 42}

Examples:

List all findings:

jxscout-pro-v2 -c get-findings

List only critical and high severity findings:

jxscout-pro-v2 -c get-findings --severity critical --severity high

List findings of a specific kind with pagination:

jxscout-pro-v2 -c get-findings --kind xss --limit 10 --offset 0

Retrieve a finding

jxscout-pro-v2 -c get-finding --kind <kind> --dedup-key <key>

Returns JSON with the finding details if it exists, or {"found": false} if not.

Guidelines

• Be specific in descriptions: "postMessage handler in /static/js/widget.js:145 accepts messages from any origin and passes event.data.url to window.location.href" is useful. "Possible open redirect" is not.
• Use dedup keys to keep findings clean. Good dedup keys: endpoint paths, filename:line, handler signatures.
• Severity guide:
  • critical -- direct impact with no user interaction (e.g. auth bypass, RCE)
  • high -- significant impact, may need minimal interaction (e.g. stored XSS, IDOR on sensitive data)
  • medium -- real impact but with limitations (e.g. reflected XSS needing specific conditions, CSRF on state-changing actions)
  • low -- interesting but limited impact (e.g. information disclosure, useful gadget for chaining)
• Metadata is useful for machine-readable details: {"endpoint": "/api/users", "parameter": "callback", "payload": "javascript:alert(1)"}.
• Reference HTTP evidence: if http_requests/ exists in the project, you can reference captured request/response files in metadata (e.g. {"evidence_request": "http_requests/target.com/api/users/GET/20260208_155236_200.req"}) to tie findings to real traffic.