Configuration

QScan is configured entirely through environment variables. There is no configuration file to manage.

Environment Variables

Required

Variable	Description
REGISTRATION_TOKEN	Authentication token from app.qpoint.io (Settings -> API Tokens). Used for Pulse API authentication and, when using Qpoint-managed S3 storage, as the S3 access key.

Pulse Connectivity

Variable	Default	Description
PULSE_ENDPOINT	https://api-pulse.qpoint.io	Pulse API endpoint URL. Override only for on-premises Pulse deployments.

Worker Pool

Variable	Default	Description
NUM_POLLERS	1	Number of concurrent threads polling Pulse for scan jobs.
NUM_SCANNERS	1	Number of concurrent threads running PII detection models.
MEMORY_LIMIT_FRACTION	0.9	Fraction of available memory QScan is allowed to use before throttling.

Metrics

Variable	Default	Description
METRICS_PORT	9090	Port for the Prometheus metrics and health check HTTP endpoint. We recommend setting this to 8080 in container deployments for compatibility with Cloud Run and common ingress defaults.

S3 Storage

Variable	Default	Description
S3_ENDPOINT_URL	https://s3.warehouse.qpoint.io	S3-compatible endpoint URL. Set this when using your own storage (AWS S3, GCS, MinIO).
S3_BUCKET_NAME	assets	Name of the S3 bucket where Qtap stores artifacts.
S3_REGION_NAME	us-east-1	S3 region.
AWS_ACCESS_KEY_ID	(derived from REGISTRATION_TOKEN when using default endpoint)	S3 access key. When using Qpoint-managed storage, this is set automatically from the registration token.
AWS_SECRET_ACCESS_KEY	unset	S3 secret key. Required when using your own S3 storage.

Logging

Variable	Default	Description
LOG_LEVEL	(not set)	Log verbosity: debug, info, warning, error.
LOG_ENCODING	(not set)	Log format: json for structured logging, omit for plain text.

---

S3 Storage Configuration

QScan supports any S3-compatible object storage:

• Qpoint-managed storage (default) -- No additional configuration needed. The registration token is used as the S3 access key automatically.

• AWS S3 -- Set S3_ENDPOINT_URL to your S3 endpoint (or omit to use the AWS default), and provide AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY.

• Google Cloud Storage -- Use the S3-compatible endpoint: https://storage.googleapis.com. Provide HMAC keys as the access and secret keys.

• MinIO / Garage / other S3-compatible -- Set S3_ENDPOINT_URL to your endpoint and provide credentials.

The S3 configuration in QScan must match the object store configured in your Qtap deployment. QScan reads artifacts that Qtap writes, so both must point to the same bucket and endpoint.

---

Qtap-Side Configuration

To enable PII scanning, add the qscan plugin to a stack in your Qtap configuration (YAML mode) or via Qplane (Stacks and Plugins):

stacks:
  sensitive_data_scanning:
    plugins:
      - type: http_metrics
      - type: report_usage
      - type: access_logs
        config:
          mode: summary
      - type: qscan
        config:
          record_document: true
          cache_ttl: 24h
          cache_size: 4096
          sample_baseline: 10
          sample_rate: 0.1
          monitors:
            - type: PERSON
              record_value: false
            - type: EMAIL_ADDRESS
              record_value: false
            - type: PHONE_NUMBER
              record_value: false
            - type: US_SSN
              record_value: false
            - type: CREDIT_CARD
              record_value: false
            - type: STREET_ADDRESS
              record_value: false
            - type: US_BANK_NUMBER
              record_value: false
            - type: US_DRIVER_LICENSE
              record_value: false
            - type: LOCATION
              record_value: false
            - type: ORGANIZATION
              record_value: false

Qtap Plugin Options

Option	Default	Description
record_document	false	Whether to record the full document content alongside PII findings.
cache_ttl	24h	How long to cache scan results for repeated requests to the same endpoint.
cache_size	4096	Maximum number of entries in the scan result cache.
sample_baseline	10	Number of initial requests to always scan before applying the sample rate.
sample_rate	0.1	Fraction of requests to scan after the baseline (0.0 to 1.0).
qscan_cloud	false	Set to true to use Qpoint's hosted QScan cloud service instead of a self-hosted QScan deployment. When enabled, Qtap sends artifacts to Qpoint's cloud for scanning.
monitors	(none)	List of PII types to detect. Each entry specifies a type and whether to record_value.

Monitor Types

Supported PII types for the monitors list:

PERSON, EMAIL_ADDRESS, PHONE_NUMBER, LOCATION, US_SSN, STREET_ADDRESS, CREDIT_CARD, US_BANK_NUMBER, US_DRIVER_LICENSE, ORGANIZATION

Setting record_value: false reports the detection without storing the actual sensitive value.

---

Scaling Guidance

Pollers vs Scanners

• Pollers fetch scan jobs from Pulse. Increasing pollers helps when job queue depth is high.

• Scanners run the ML models. Increasing scanners improves throughput but requires proportionally more memory and CPU.

Recommended Configurations

Workload	Pollers	Scanners	Memory	CPU
Light (< 100 scans/hour)	1	1	12 GB	2 vCPUs
Moderate (100-1000 scans/hour)	2	2	24 GB	6 vCPUs
Heavy (> 1000 scans/hour)	2	2	16 GB + GPU	4 vCPUs + 1 GPU

For heavy workloads, horizontal scaling (multiple QScan instances) is more effective than increasing pollers and scanners on a single instance. Each scanner thread loads its own copy of the ML models, so memory usage scales linearly with NUM_SCANNERS.