Assessment Tool Download

How the session is established (no typing on the PC)

1. Tech opens /scan on the assessment computer. The page calls createScanSession, which mints a device_session_id and a short session_code (e.g. SCAN-A1B2), and renders a QR of /authorize-scan?session=<device_session_id>.
2. Tech scans the QR with their phone (already signed into the dashboard), picks the client, and taps Authorize. Server binds the customer/project to that session, flips it to paired, and issues a one-time upload_key.
3. The /scan page is polling and shows "Authorized for <client>". The EXE now claims the session and uploads (below).

1. EXE reads the session code

The EXE needs the session_code shown on the /scan page. Easiest path: the packaged EXE is launched by the /scan page (custom URL protocol handler or a small downloaded launcher file that carries the code), OR the tech copies/pastes the session_code into the EXE once. This is the only value the EXE ever needs.

2. EXE exchanges the code for the upload key

Only works after the tech has authorized on their phone (status = paired):

// Request
{ "session_code": "SCAN-A1B2" }

// Response (200) — bound to the exact client the phone authorized
{
  "success": true,
  "upload_key": "…one-time key…",
  "customer_id": "…",
  "project_id": "…"
}

// 403 if not yet authorized / expired — poll every few seconds until 200

The customer_id/project_id are resolved server-side from the session the phone authorized — the EXE never picks the client and can't upload to the wrong one.

3. EXE runs the scan and uploads to THIS session

Header Authorization: Bearer <upload_key>, body { "assessment_data": { … } } (full schema in the section below).

4. Session auto-invalidates on confirm

On a successful upload the server burns the upload_key, sets the session to assessment_uploaded, and stamps expired_at. The /scan page detects this and shows "Upload complete — session closed", so the session on that computer can't be reused. The EXE should discard the key from memory after a 200.

1. Detect the active session by its session ID

The browser's /scan page holds the livedevice_session_id / session_code. When the EXE launches on this computer it must pick up that same session ID (via the launcher file / URL protocol that opened it, or the pastedsession_code), confirm the session is paired, and bind every scan it runs to that one session so results land on the correct prospect.

2. Run the four scan classes

On launch the EXE presents a menu of the four scan types. The tech can run any of them; results are uploaded per-type and merged into this session's assessment.

3. Auto-check completed scans, offer only the outstanding ones

The EXE is generic — never recompiled per prospect. Right after pairing, it calls the checklist endpoint with the upload_key it just received. The server resolves the prospect and returns which of the four scan types already have data. The EXE then checks & disables the completed ones and pre-checks the outstanding ones. Re-call it after each upload to refresh the boxes live.

// Request  (Authorization: Bearer <upload_key>, or in body)
{ "upload_key": "…the key from validatePairing…" }

// Response (200)
{
  "success": true,
  "scan_completion": { "workstation": true, "network": false, "wifi": false, "external": false },
  "scans": [
    { "key": "workstation", "label": "Workstation Scan", "completed": true },
    { "key": "network",     "label": "Network Scan",     "completed": false },
    { "key": "wifi",        "label": "WiFi Analysis",    "completed": false },
    { "key": "external",    "label": "External Scan",    "completed": false }
  ],
  "outstanding": ["network", "wifi", "external"]
}

completed: true → render checked & disabled.completed: false → render pre-checked so the tech runs it. EachcompleteAssessmentUpload flips its type to complete, so the next call reflects it — across all machines and sites.

1. What to look for

• Credit card numbers — 13–19 digit sequences that pass a Luhn checksum (reduces false positives) in the common Visa/Mastercard/Amex/Discover prefixes. Ignore whitespace/dashes between groups.
• US Social Security Numbers — XXX-XX-XXXX pattern (and the 9-digit unformatted form), excluding known-invalid ranges (000, 666, 900–999 area; 00 group; 0000 serial).
• Open and read text-extractable files: .txt .csv .log .rtf .doc/.docx .xls/.xlsx .pdf .json .xml .html. Skip binaries, media, and system/program directories.

2. Upload the results inside assessment_data

Add a pii_scan object to the normalcompleteAssessmentUpload payload. No new endpoint — same session, same upload key.

{
  "assessment_data": {
    // ...other scan sections...
    "pii_scan": {
      "files_scanned": 48213,
      "credit_card_matches": 12,
      "ssn_matches": 5,
      "files_with_findings": [
        { "path": "C:\\Users\\jdoe\\Desktop\\customers.csv", "credit_card_matches": 9, "ssn_matches": 0 },
        { "path": "C:\\Shared\\HR\\employees.xlsx", "credit_card_matches": 0, "ssn_matches": 5 },
        { "path": "C:\\Temp\\export.txt", "credit_card_matches": 3, "ssn_matches": 0 }
      ]
      // NOTE: never include the matched values themselves — counts + paths only
    }
  }
}

files_with_findings may also be a plain array of path strings if you don't want per-file counts. The platform tallies the counts, lists the files, and computes the hard/soft breach-cost exposure automatically.