> For the complete documentation index, see [llms.txt](https://docs.qpoint.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.qpoint.io/getting-started/qscan/configuration.md). # 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](https://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. {% hint style="info" %} 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. {% endhint %} *** ## 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): ```yaml 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`. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.qpoint.io/getting-started/qscan/configuration.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.