Sensitive Data Discovery

Sensitive Data Discovery scans your managed devices for files containing personally identifiable information (PII), payment card data (PCI), protected health information (PHI), credentials, and financial records. The system uses pattern-based detection to identify sensitive content, assigns risk scores and confidence levels to each finding, and provides remediation workflows to encrypt, quarantine, or securely delete the offending files. A centralized dashboard tracks open findings, risk distribution, and remediation progress across your fleet.

Scans can be triggered manually for specific devices or scheduled through scan policies. Each scan runs on the agent side, and results are reported back to the API where findings are stored, deduplicated across scans, and made available for reporting and remediation.

---

Key Concepts

Data Classification Types

Type	Description
pii	Personally identifiable information — names, addresses, phone numbers, email addresses, government IDs (SSN, passport numbers)
pci	Payment card industry data — credit/debit card numbers, CVVs, cardholder data
phi	Protected health information — medical records, insurance IDs, health conditions, prescription data
credential	Stored credentials — API keys, passwords, tokens, private keys, connection strings
financial	Financial records — bank account numbers, routing numbers, tax documents, financial statements

Risk Levels

Risk	Description
low	Finding has limited exposure potential — low match count, non-sensitive file location, or low confidence
medium	Finding warrants review — moderate match count or sensitive file type
high	Finding requires attention — multiple matches in an accessible location or high-confidence detection
critical	Finding demands immediate action — credentials in plaintext, unprotected PCI data, or high match count with high confidence

Finding Statuses

Status	Description
open	Active finding that has not been addressed
remediated	Finding has been remediated (encrypted, quarantined, deleted, or manually marked)
accepted	Risk has been explicitly accepted by an administrator
false_positive	Finding has been determined to be a false positive

Remediation Actions

Action	Destructive	Description
encrypt	Yes	Encrypt the file in place using the configured encryption key
quarantine	Yes	Move the file to a quarantine directory on the device
secure_delete	Yes	Permanently and securely delete the file
accept_risk	No	Acknowledge the finding and accept the risk
false_positive	No	Mark the finding as a false positive
mark_remediated	No	Manually mark the finding as remediated

Caution

Destructive actions (encrypt, quarantine, secure_delete) require confirm: true in the request body. The secure_delete action additionally requires a valid secondApprovalToken when the SENSITIVE_DATA_REQUIRE_SECOND_APPROVAL environment variable is enabled.

---

Scan Policies

Scan policies define the detection configuration, file scope, and schedule for sensitive data scans. Each policy is scoped to an organization and specifies which data types to detect, which paths to scan, and how often to run.

Creating a Policy

POST /sensitive-data/policies
Content-Type: application/json
Authorization: Bearer <token>

{
  "orgId": "uuid",
  "name": "Weekly PII & Credential Scan",
  "scope": {
    "includePaths": ["/Users", "/home", "C:\\Users"],
    "excludePaths": ["/Users/*/Library", "C:\\Windows"],
    "fileTypes": [".txt", ".csv", ".xlsx", ".json", ".env", ".conf"],
    "maxFileSizeBytes": 104857600,
    "workers": 4,
    "timeoutSeconds": 600
  },
  "detectionClasses": ["pii", "credential"],
  "schedule": {
    "enabled": true,
    "type": "interval",
    "intervalMinutes": 10080,
    "timezone": "America/Chicago"
  },
  "isActive": true
}

Policy Fields

Field	Type	Required	Description
orgId	UUID	No	Organization ID. Auto-resolved for org-scoped tokens
name	string	Yes	Policy name (max 200 chars)
scope	object	No	Scan scope configuration (see below)
detectionClasses	string[]	Yes	Data types to detect: pii, pci, phi, credential, financial (1-5)
schedule	object	No	Scan schedule configuration (see below)
isActive	boolean	No	Whether the policy is active (default true)

Scope Configuration

Field	Type	Description
includePaths	string[]	Paths to scan (max 256, each up to 2,048 chars)
excludePaths	string[]	Paths to exclude from scanning (max 256)
fileTypes	string[]	File extensions to scan (max 128, each up to 32 chars)
maxFileSizeBytes	integer	Maximum file size to scan (1 KB to 1 GB)
workers	integer	Concurrent scan workers (1-32)
timeoutSeconds	integer	Scan timeout in seconds (5-1,800)
suppressPaths	string[]	Paths to suppress in findings (max 256)
suppressPatternIds	string[]	Pattern IDs to suppress (max 200)
suppressFilePathRegex	string[]	Regex patterns for file paths to suppress (max 80)
ruleToggles	object	Per-rule enable/disable overrides (key: rule ID, value: boolean)

Schedule Configuration

Field	Type	Description
enabled	boolean	Whether the schedule is active (default true)
type	string	Schedule type: manual, interval, or cron
intervalMinutes	integer	Scan interval in minutes (5 to 10,080 / one week)
cron	string	Cron expression (when type is cron)
timezone	string	Timezone for scheduled scans
deviceIds	UUID[]	Specific devices to scan (max 1,000). If omitted, scans all devices in the org

Updating a Policy

PUT /sensitive-data/policies/:id
Content-Type: application/json

{
  "name": "Updated Scan Policy",
  "detectionClasses": ["pii", "credential", "pci"],
  "isActive": true
}

Deleting a Policy

DELETE /sensitive-data/policies/:id

---

Running Scans

Triggering a Manual Scan

POST /sensitive-data/scan
Content-Type: application/json
Authorization: Bearer <token>

{
  "deviceIds": ["device-uuid-1", "device-uuid-2"],
  "policyId": "policy-uuid",
  "detectionClasses": ["pii", "credential"],
  "scope": {
    "includePaths": ["/home"],
    "fileTypes": [".txt", ".csv", ".env"],
    "maxFileSizeBytes": 52428800
  },
  "idempotencyKey": "scan-2026-02-15-batch-1"
}

Field	Type	Required	Description
deviceIds	UUID[]	Yes	Devices to scan (1-200)
policyId	UUID	No	Use an existing policy’s scope and detection classes
scope	object	No	Override the scan scope (takes precedence over policy scope)
detectionClasses	string[]	No	Override detection classes (takes precedence over policy)
idempotencyKey	string	No	Client-provided idempotency key (8-128 chars). Also accepted via Idempotency-Key header

The API creates one scan record per device and enqueues each scan through BullMQ. Decommissioned devices are excluded. The response includes the created scans, the count of successfully queued jobs, and any skipped device IDs.

Note

Idempotency protection prevents duplicate scan submissions. If a scan with the same idempotency key and request fingerprint (based on device IDs, policy, scope, and detection classes) was created within the last 24 hours, the API returns the existing scans instead of creating new ones. The idempotentReuse field in the response indicates whether reuse occurred.

Scan Statuses

Status	Description
queued	Scan created and enqueued for the agent
running	Agent is actively scanning the device
completed	Scan finished — results include findings summary
failed	Scan encountered an error

Listing Recent Scans

GET /sensitive-data/scans?limit=50

Returns recent scans ordered by creation time, with device hostname, policy reference, status, and timing information.

Getting Scan Details

GET /sensitive-data/scans/:id

Returns full scan details including a findings summary with counts by risk level and status. If the scan has pre-computed summary counters in its summary JSONB, those are returned directly. Otherwise, findings are aggregated on the fly.

---

Findings and Reports

Querying Findings

GET /sensitive-data/report?status=open&risk=critical&dataType=credential&page=1&limit=50

Report Query Parameters

Parameter	Type	Description
status	string	Filter by status: open, remediated, accepted, false_positive
risk	string	Filter by risk level: low, medium, high, critical
dataType	string	Filter by data type: pii, pci, phi, credential, financial
deviceId	UUID	Filter findings for a specific device
scanId	UUID	Filter findings from a specific scan
page	integer	Page number for pagination
limit	integer	Results per page (default 200)

Finding Response Fields

Field	Type	Description
id	UUID	Unique finding identifier
orgId	UUID	Organization ID
deviceId	UUID	Device where the file was found
deviceName	string	Hostname of the device
scanId	UUID	Scan that discovered the finding
filePath	string	Full path to the file containing sensitive data
dataType	string	Classification type: pii, pci, phi, credential, financial
patternId	string	Identifier of the detection pattern that matched
matchCount	integer	Number of matches found in the file
risk	string	Risk level: low, medium, high, critical
confidence	float	Detection confidence score (0.0 to 1.0)
fileOwner	string	File owner on the device
fileModifiedAt	ISO 8601	When the file was last modified
firstSeenAt	ISO 8601	When this finding was first detected
lastSeenAt	ISO 8601	When this finding was last confirmed
occurrenceCount	integer	Number of scans that have found this file
status	string	Current status: open, remediated, accepted, false_positive
remediationAction	string	Action taken (if any)
remediatedAt	ISO 8601	When remediation occurred

---

Dashboard

The dashboard endpoint aggregates all findings data into a single response for the sensitive data overview:

GET /sensitive-data/dashboard

Dashboard Response

{
  "data": {
    "totals": {
      "findings": 1250,
      "open": 842,
      "criticalOpen": 23,
      "remediated24h": 45,
      "averageOpenAgeHours": 168.5
    },
    "byDataType": {
      "pii": 520,
      "credential": 380,
      "pci": 200,
      "phi": 100,
      "financial": 50
    },
    "byRisk": {
      "low": 600,
      "medium": 350,
      "high": 200,
      "critical": 100
    }
  }
}

Field	Description
totals.findings	Total number of findings across all statuses
totals.open	Number of findings in open status
totals.criticalOpen	Number of critical-risk findings that are still open
totals.remediated24h	Number of findings remediated in the last 24 hours
totals.averageOpenAgeHours	Average age of open findings in hours
byDataType	Finding count broken down by data classification
byRisk	Finding count broken down by risk level

---

Remediation

Remediating Findings

POST /sensitive-data/remediate
Content-Type: application/json
Authorization: Bearer <token>

{
  "findingIds": ["finding-uuid-1", "finding-uuid-2"],
  "action": "quarantine",
  "confirm": true,
  "quarantineDir": "/var/lib/breeze/quarantine/sensitive",
  "dryRun": false
}

Remediation Request Fields

Field	Type	Required	Description
findingIds	UUID[]	Yes	Findings to remediate (1-250)
action	string	Yes	encrypt, quarantine, secure_delete, accept_risk, false_positive, mark_remediated
confirm	boolean	Conditional	Required for destructive actions (encrypt, quarantine, secure_delete)
dryRun	boolean	No	Preview which findings would be affected without making changes (default false)
secondApprovalToken	string	Conditional	Required for secure_delete when second approval is enabled
encryptionKeyRef	string	No	Reference to the encryption key (for encrypt action)
encryptionKeyVersion	string	No	Version of the encryption key
quarantineDir	string	No	Custom quarantine directory path on the device

How Remediation Works

1. Non-destructive actions (accept_risk, false_positive, mark_remediated) update the finding status directly in the database. No command is sent to the agent.

2. Destructive actions (encrypt, quarantine, secure_delete) queue a command to the target device’s agent via the command queue. Each finding becomes a separate command targeting the specific file path.

3. Dry run mode returns the list of eligible findings and their file paths without making any changes, allowing you to preview the impact before committing.

4. Second approval can be required for secure_delete operations by setting the SENSITIVE_DATA_REQUIRE_SECOND_APPROVAL environment variable. When enabled, a valid secondApprovalToken must be provided.

Remediation Response

For destructive actions, the response includes queued commands and any failures:

{
  "data": {
    "queued": [
      { "findingId": "uuid", "commandId": "uuid" }
    ],
    "failed": [
      { "findingId": "uuid", "error": "Device is offline" }
    ],
    "updated": 5
  }
}

Note

When findings are remediated with mark_remediated, a compliance.sensitive_data_remediated event is published through the event bus for integration with alerting and compliance tracking systems.

---

API Reference

Scans

Method	Path	Description
POST	/sensitive-data/scan	Trigger a manual scan on one or more devices
GET	/sensitive-data/scans	List recent scans with status and summary
GET	/sensitive-data/scans/:id	Get scan details with findings breakdown

Findings and Reports

Method	Path	Description
GET	/sensitive-data/report	Query findings with filtering and pagination
GET	/sensitive-data/dashboard	Aggregated dashboard with totals, risk, and data type distribution

Remediation

Method	Path	Description
POST	/sensitive-data/remediate	Remediate findings (destructive or non-destructive)

Policies

Method	Path	Description
GET	/sensitive-data/policies	List all scan policies for the organization
POST	/sensitive-data/policies	Create a new scan policy
PUT	/sensitive-data/policies/:id	Update an existing policy
DELETE	/sensitive-data/policies/:id	Delete a policy

Note

All sensitive data endpoints require authentication and one of these scopes: organization, partner, or system. Organization-scoped tokens are automatically restricted to their own organization’s data.

---

Troubleshooting

Scan stuck in queued status. The scan was created but the agent has not started processing it. Verify that the target device is online and the agent is connected. Check that BullMQ workers are running and processing the sensitive data scan queue. If the scan enqueue failed, the creation response includes an enqueueFailures count greater than zero.

No findings returned after a completed scan. The scan completed but did not detect any sensitive data matching the configured detection classes and scope. Verify the detectionClasses include the types you expect to find. Check the scope.includePaths to ensure the correct directories are being scanned. Review scope.excludePaths and suppressPaths to make sure the target files are not being excluded. Also check scope.maxFileSizeBytes — files larger than the limit are skipped.

Duplicate scan created despite idempotency key. Idempotency checks match on both the key and the request fingerprint (a SHA-256 hash of device IDs, policy, scope, and detection classes). If any of these values differ between requests, the fingerprint will not match and a new scan will be created. Idempotency protection also only applies to scans created within the last 24 hours.

Destructive remediation rejected with confirm=true error. Destructive actions (encrypt, quarantine, secure_delete) require confirm: true in the request body. If the secure_delete action is rejected despite confirmation, check whether the SENSITIVE_DATA_REQUIRE_SECOND_APPROVAL environment variable is enabled — if so, a valid secondApprovalToken must also be provided.

Remediation command failed to queue for a device. When a destructive remediation command fails to queue, the finding ID appears in the failed array of the response with an error message. Common causes include the device being offline or the command queue being unavailable. The finding’s remediationAction and remediationMetadata are still updated to reflect the attempted action, but the agent will not receive the command until it is re-queued.

Dashboard shows stale totals. The dashboard computes totals by scanning all findings in real time. If the finding count is large, the response may take a moment to compute. The averageOpenAgeHours is calculated from each open finding’s lastSeenAt timestamp. If scans are not running regularly, the age values may appear inflated.