Session Management

After a scan completes, its session directory can be uploaded to the Bullium Consulting consultation portal, pushed with a shareable report link, or re-uploaded after a report-template change. Three CLIs cover these flows: upload_session.sh, push_session.sh, and refresh_reports.sh. All three share the multipart uploader in submit_session.sh.

For the wire format and portal endpoints, see the API Contract.

Credentials

Every uploader reads portal credentials from a config file (the -c flag) or from direct URL and key flags. In config files, NV_API_KEY takes precedence over the legacy CONSULTATION_API_KEY alias, and both are accepted for backward compatibility. See Report Configuration and Secrets Management for where these live and how to rotate them.

Session Upload

scripts/upload_session.sh uploads a completed session using a config file for credentials. It defaults to the most recent session.

upload_session.sh -c <config> [options]

Required:
  -c <file>           Report config file (CONSULTATION_API_URL + NV_API_KEY)

Session Selection (pick one, defaults to --latest):
  -s <session_dir>    Path to a session directory
  -i <session_id>     Session ID, for example 20260224_120000
  --latest            Use the most recent session (default)

Options:
  -r <file>           HTML report file (overrides auto-detection from the session dir)
  -e <file>           Executive summary HTML (auto-detected from the session dir)
  --dry-run           Show what would be uploaded without sending
  -h, --help          Show help

# Upload the most recent session (default)
./scripts/upload_session.sh -c ~/netvuln-tool/configs/acme.conf

# Upload a specific session by ID
./scripts/upload_session.sh -c ~/netvuln-tool/configs/acme.conf -i 20260224_120000

# Upload a specific session by path
./scripts/upload_session.sh -c ~/netvuln-tool/configs/acme.conf -s ~/netvuln-tool/sessions/20260224_120000

# Preview without sending
./scripts/upload_session.sh -c ~/netvuln-tool/configs/acme.conf --dry-run

Upload is also available as option 9 in the interactive menu (vulnscan_menu.sh).

Automatic push after a scan

You rarely need to run the uploader by hand. When the config passed to the recon pipeline with -c defines both CONSULTATION_API_URL and NV_API_KEY (or CONSULTATION_API_KEY), the session is submitted automatically once the pipeline finishes, and a shareable report link is returned on success. The manual uploaders exist for re-pushing older sessions or for hosts where the scan and the upload happen separately.

Session Push

scripts/push_session.sh submits a previously completed session and reports the portal session ID and shareable link that come back in the response. It can auto-discover artifacts from a session directory or take a JSON path directly.

push_session.sh (-d <dir> | -j <file>) [options]

Required (one of):
  -d <dir>            Session directory (auto-discovers JSON, log, report, exec summary)
  -j <file>           Path to session_results.json directly

Optional:
  -R <file>           Path to the HTML report file
  -e <file>           Path to the executive summary HTML (auto-detected from the session dir)
  -c <file>           Config file (for CONSULTATION_API_URL and NV_API_KEY)
  -u <url>            API URL (overrides the config file)
  -k <key>            API key (overrides the config file)
  -h, --help          Show help

# Push a session directory using a config file
./scripts/push_session.sh -d ~/netvuln-tool/sessions/20260224_120000 \
    -c ~/netvuln-tool/configs/acme_corp.conf

# Push with an explicit URL and key
./scripts/push_session.sh -d ~/netvuln-tool/sessions/20260224_120000 \
    -u https://bullium.com/api/upload -k nvt_pro_<hex>

# Push a specific JSON alongside its report
./scripts/push_session.sh -j /path/to/session_results.json \
    -R /path/to/report.html -c config.conf

On a successful upload the tool prints the returned session ID and, when the portal issues one, a shareable report link of the form:

https://<your-portal>/share/?token=<64-hex-chars>

That link requires no login. The long random token is the credential, so treat the URL as sensitive.

Remote agents

For agents managed through Command and Control, pushing is handled remotely. Dispatch a run_scan command with upload: true to auto-push the resulting session, or send a push_session command (optionally with a specific session_id, defaulting to the latest) to push an already-completed session. Both report the portal session ID back through the agent's heartbeat.

Report Refresh

When the report template (report_template.sh) changes (cosmetic fixes, new features, bug fixes), you can regenerate and re-upload reports for existing portal sessions without re-running the scan. scripts/refresh_reports.sh drives the PUT /api/refresh endpoint, which replaces report artifacts in place.

refresh_reports.sh [options] SESSION_ID [SESSION_ID ...]

Required (one of):
  -c <config.conf>     Config file with NV_API_URL and NV_API_KEY
  -u <url> -k <key>    API URL and key directly

Options:
  --all                Refresh every session on the portal
  --dry-run            Regenerate locally without uploading
  -h, --help           Show help

# Refresh a specific session
./scripts/refresh_reports.sh -u https://bullium.netlify.app/api \
    -k nvt_pro_<hex> 20260318_103739

# Refresh every session
./scripts/refresh_reports.sh -u https://bullium.netlify.app/api \
    -k nvt_pro_<hex> --all

# Dry run: regenerate locally, upload nothing
./scripts/refresh_reports.sh -u https://bullium.netlify.app/api \
    -k nvt_pro_<hex> --dry-run 20260318_103739

Refresh, not re-push

push_session.sh cannot re-upload to a session that already exists on the portal (it returns an HTTP 500 duplicate error). Use refresh_reports.sh for that. The refresh endpoint accepts only report.html and exec_summary.html; it cannot update session JSON or pipeline logs. Share-page links stay the same after a refresh, because the share token is permanent.

refresh_reports.sh expects the NV_API_URL and NV_API_KEY variable names in a config file. If your config uses CONSULTATION_API_URL / CONSULTATION_API_KEY, pass credentials directly with -u and -k instead.

Under the Hood

Both upload_session.sh and push_session.sh delegate the actual transfer to submit_session.sh, a shared library that performs the multipart upload (25 MB maximum). It sends the session JSON plus, when present, the pipeline log, the report HTML, and the executive-summary HTML, and it exposes the portal's session ID and share token to the calling script on success.