Connectors

One page per source PYXA can read: what it brings, what it can and cannot prove, how to get what it needs, and what goes wrong. Configure each one under Administration, Integrations. Every connector has a Test connection button, which states what is wrong rather than reporting a generic failure.

Before you start: what a connector may conclude

PYXA sorts sources by the strongest thing their data can prove. A finding reaches Verified only when a verifying scanner observes it gone.

Several scanners, one host. When two scanners report the same machine (same IP and host name, case and DNS domain ignored), PYXA keeps one asset. Its last scan date is the newest from any scanner; host name, IP and OS come from the first scanner and are only filled in by the others.

Schedules. Each connector syncs on its own schedule (Administration, Collection). Evolution and the Command Center always hold every source's latest run, so a scanner that has not run yet today keeps its last picture; the trend says which sources it carried and from when.

File imports: where files go

Every file connector reads from one folder on the PYXA server, the import folder: /data/imports by default (CSV_IMPORT_DIR in .env). In the Docker deployment it is the csv_imports volume, mounted in the django and worker containers. A path outside it is refused, so a connector cannot be pointed at other files on the server.

Ways to get a file there:

• Push it over HTTPS with the connector's upload key, from a CI pipeline, a scheduled job or a script: pyxa push export.csv --wait or one curl. PYXA stores the file, points the connector at it and imports it at once, and the sender gets the import's summary. This is the recommended way; see file-push.md for the key, the CLI, and GitHub Actions and GitLab CI examples.
• Have the tool or a scheduled job write into a share mounted at that folder; the connector reads it at its next schedule.
• Copy it by hand (docker compose cp report.csv django:/data/imports/).

The connection test says exactly what is wrong: no path set, a path outside the import folder, a folder that does not exist, a folder with no file in it yet, a folder given where a file is expected, or a file PYXA cannot read.

Following a sync

Every connector sync writes its progress to the worker log as it runs, one line per step, prefixed with the task's name:

docker logs -f patchwork_celery_bulk 2>&1 | grep -E "run_[a-z_]+_sync|BloodHound import"
docker exec patchwork_celery_bulk celery -A patchwork inspect active

One sync per connector runs at a time, however it was started: Sync now, a file push, pyxa_admin connectors sync, or a schedule. A second one started while the first runs is not run; the worker log says connector N is already syncing; this run was not started, and a pushed file's receipt says to send it again once the running sync ends.

A sync whose worker stops (a restart, the memory limit) is released after 15 minutes without a heartbeat and marked failed with that reason.

Every call a connector makes passes PYXA's outbound guard, which records it and, in enforce mode, refuses a host no configuration names: see outbound-connections.md.

Verifiers

Qualys VM

Reads: hosts, detections (confirmed and potential), the knowledge base, tags. Needs: an API user with API access enabled and read access to the assets you want, and your platform's API URL (for example https://qualysapi.qualys.eu). Configuration: base_url, username, password. Manual run: python manage.py sync_qualys_snapshot (options: --since-days 7, --tag-include "EMEA,APAC", --fetch-kb, --dry-run). Common errors: a 401 means the user or password; a 403 usually means API access is not enabled for the user, or the platform URL belongs to another region.

Tenable: Vulnerability Management, Security Center, Nessus

One connector, three products, chosen by the host:

• Tenable Vulnerability Management (cloud, formerly Tenable.io): cloud.tenable.com. Uses the asset and vulnerability export APIs.
• Tenable Security Center (on-premises, formerly Tenable.sc): your console. Reads the cumulative vulnerability database.
• Nessus Professional, Expert or Manager: https://<host>:8834. Reads the results of finished scans.

Needs: an access key and secret key. In the cloud and in Nessus they are under Settings, My Account, API Keys; in Security Center, under the user's API keys (version 5.13 and later). Configuration: host, access_key, secret_key, optionally platform (tio, sc or nessus; detected from the host when omitted). Manual run: python manage.py sync_tenable --source-id <id>. Common errors: a self-signed certificate on Nessus is reported as such, with how to trust it; a 403 from the cloud usually means the keys belong to a user without the Basic role on the assets.

Rapid7 InsightVM

Two APIs, chosen by the host:

• Security Console (on-premises): https://<console>:3780, with a console user's name and password.
• Insight Platform (cloud): https://<region>.api.insight.rapid7.com, with an Insight API key.

Configuration: host, port, api_key and api_secret: the console user's name and password on-premises, or the Insight API key alone in api_key for the cloud. Optionally site_id to read one site. Manual run: python manage.py sync_rapid7 --source-id <id>.

OpenVAS / Greenbone Community Edition

Reads: hosts, results and NVTs over the Greenbone Management Protocol (GMP), which is XML over TLS, not HTTP. Needs: a GVM user, and the GMP port reachable from PYXA (9390 by default; 9392 is the web interface, not GMP). Configuration: host, port, username, password, max_report_age_days (optional, default 30), timeout_seconds (optional, default 120, 10 to 3600: how long to wait for each answer). What a sync reads:

• Hosts from Assets > Hosts. A scan adds its hosts there only when its task has "Add results to Assets" set to yes.
• Results from each task's latest finished report, at QoD 70 or more. Results at severity 0 (Log) prove a host was scanned and import no finding. A scan still running contributes nothing until it finishes.
• Scopes split across tasks run on different days are joined: every task's latest report is read on each sync. A task whose latest finished report is older than max_report_age_days (default 30) is not read; its hosts keep their last detections, and nothing on them is closed on old evidence. The connector page's Scan coverage table lists each task, its target, when its report finished, and whether it was read.
• NVT details only for the NVTs those results cite and PYXA does not hold yet. python manage.py sync_openvas --source-id <id> --kb-only reads and refreshes the whole catalogue, which is over 100,000 NVTs on a current feed.

Limit: the Greenbone Community Containers expose GMP only on gvmd's unix socket. PYXA needs a TLS listener in front of it (a socat OPENSSL-LISTEN:9390 relay to /run/gvmd/gvmd.sock is enough). Common errors: a certificate that cannot be verified is reported as such; set the CA certificate when the appliance has its own authority. A timeout names the step it stalled on: no answer to the connection (address, routing, or the wrong port), no answer to the sign-in (the web interface's port 9392, or gvmd busy loading its feed), or a report that took longer than timeout_seconds to return (raise it).

Agent and cloud verifiers: how absence is read

Defender, Spotlight, Inspector and Wiz report only what is wrong now; a fixed vulnerability simply stops appearing. PYXA reads that absence as a fix only on assets the tool actually assessed in that pass:

• Defender, Spotlight: a device counts when its sensor reported within stale_days (default 7). A laptop that was off keeps its findings.
• Inspector: a resource counts when its coverage scan status is ACTIVE.
• Wiz: a workload counts when it carries an open finding, or Wiz resolved one of its findings within resolved_days (default 14).

A pass that could not read everything (a region refused, a permission missing) is partial and closes nothing. All seven live connectors in this section and the next run through one command: python manage.py sync_api_connector --source-id <id> (options: --assets-only, --vulns-only, --kb-only).

Microsoft Defender Vulnerability Management

Reads: devices (/api/machines), and vulnerabilities per device and software (/api/machines/SoftwareVulnerabilitiesByMachine), with Defender's exploitability level and recommended update. Needs: an Entra ID app registration with the Application permissions Machine.Read.All and Vulnerability.Read.All on WindowsDefenderATP, admin-consented, and a client secret. Configuration: tenant_id, client_id, client_secret; optionally cloud (gcc, gcchigh, dod), api_base for a regional host (https://api-eu.securitycenter.microsoft.com), stale_days. Common errors: a 403 means a permission is missing or not admin-consented; a 401 means the secret or the tenant.

CrowdStrike Falcon Spotlight

Reads: hosts (devices API) and open Spotlight vulnerabilities, with CrowdStrike's exploit status, CISA KEV flag and remediation. Needs: an API client with Vulnerabilities: Read and Hosts: Read. Without Hosts: Read every pass is partial: only hosts with an open finding are known to be assessed. Configuration: client_id, client_secret; optionally cloud (us-1, us-2, eu-1, us-gov-1) or base_url, stale_days.

Amazon Inspector

Reads: active findings on EC2 instances, ECR images and Lambda functions (package vulnerabilities and network reachability), and coverage, per region. Needs: an IAM principal with inspector2:ListFindings and inspector2:ListCoverage (the AmazonInspector2ReadOnlyAccess managed policy). Use the delegated administrator account to read every member account. Configuration: access_key_id, secret_key, optionally session_token, and regions (comma-separated). Common errors: a region where Inspector is not enabled makes that region's part of the pass fail and the run partial; remove it from regions.

Wiz

Reads: open and in-progress vulnerability findings on cloud workloads (GraphQL vulnerabilityFindings), with EPSS, exploit and KEV flags, and recently resolved findings to know which workloads were rescanned. Needs: a service account with read:vulnerabilities, and the tenant's API endpoint (User Settings, Tenant). Configuration: client_id, client_secret, api_endpoint; optionally auth_provider (auth0 for older tenants), resolved_days.

Code security

Each repository or project is an asset, of type Code repository. These connectors close their own findings when the default branch's next analysis no longer reports them, and never close a finding another source reported.

GitHub Advanced Security

Reads: the organisation's repositories, and open code scanning, Dependabot and secret scanning alerts. One finding per repository per rule, advisory or secret type. Needs: a fine-grained token (or GitHub App installation token) with read access to Code scanning alerts, Dependabot alerts, Secret scanning alerts and Metadata on the organisation's repositories. Configuration: organization, token_key; optionally base_url for GitHub Enterprise Server, families to read a subset (code-scanning,dependabot,secret-scanning). Common errors: an alert family the token cannot read, or that is off for the organisation, is named in the run, which is then partial.

GitLab Security

Reads: the group's projects (subgroups included) and its vulnerability report, detected and confirmed (SAST, dependency, container, secret detection, DAST). Needs: GitLab Ultimate, and a token with read_api from a member with at least Developer on the group. Configuration: group (full path), token_key; optionally base_url for self-managed GitLab.

Snyk

Reads: the organisation's projects, grouped into repositories (owner/repo), and their open issues (Open Source, Code, Container, IaC), with Snyk's risk score. Needs: a service account token with Org Viewer, and the organisation ID (Settings, General). Configuration: org_id, api_key; optionally region (eu, au). A deactivated project's issues keep their previous state.

Deployment claims

Microsoft Intune (API)

Reads: managed devices, and Windows Update for Business per-device update states, through Microsoft Graph. Needs: an app registration in Entra ID with these Application permissions, admin-consented: DeviceManagementManagedDevices.Read.All and DeviceManagementConfiguration.Read.All. The update states endpoint is Microsoft's beta Graph API; there is no v1.0 equivalent. Configuration: tenant_id, client_id, client_secret, optionally cloud for a national cloud. Claims: Graph reports the build a device runs (qualityUpdateVersion, for example 10.0.26100.6899) rather than a KB. PYXA keeps the build on the record, names the KB the Security Update Guide gives that build, and claims every fix on the device's OS line at or below it (see Claims from a Windows build below). Limit: a tenant with no Windows Update for Business policy has no per-device update state to read.

Patch deployment import (WSUS, SCCM, Intune, Ansible files)

Reads: a CSV or JSON export of what a deployment tool installed. Configuration: patch_file (inside the import folder), optionally tool (wsus, sccm, intune, ansible, other). When tool is not set, a source named after a tool ("Intune") is read as that tool. Columns it recognises (case, spaces and underscores ignored):

Status words are read as installed (Installed, Up to date, Success, Completed, Compliant), failed (Failed, Error, Rollback, Needs attention) or pending (anything else, including any status that starts with Not, such as Not up to date). Dates may be ISO or US (9/30/2026 10:15:00 AM). Comma, semicolon and tab separators all work.

Intune Quality update status report: in Intune, Reports, Windows updates, Quality updates, open the device status report and Export to CSV. Drop the file in the import folder and point patch_file at it.

Windows Autopatch quality update status report (columns Device name, Update status, Installed release, Target release, Build number, …): export it as it is. It names no KB; each row is read from its Build number as the build installed on the device, recorded under the KB the Security Update Guide gives that build (or "Windows 26100.6899" when the guide does not name one), with the target release and status in the record's title. The All devices report works the same way from its OS version and OS revision columns.

Claims from a Windows build

Windows quality updates are cumulative. The Security Update Guide lists, for each CVE, the Windows build each KB brings the fix in. A device that reports build 26100.6899 is claimed fixed for every CVE whose fixed build on the 26100 line has a revision of 6899 or lower; a device one month behind is claimed for the earlier month only. Only the device's own OS line is compared, and only builds the guide writes as 10.0.<build>.<rev> are used, so an Office or .NET fix is never claimed from a Windows build. As with every deployment report, this is a claim: a verifying scanner still decides whether the finding is fixed.

The builds come from the guide sync (Administration, Threat intel, Microsoft Security Update Guide). After upgrading, the next syncs read every stored release again to collect them, forty releases per run. Until then an import says that no fixed builds are held and claims nothing from builds.

After an import the summary counts what was skipped and why, with the columns the file has, for example: Synced 0 of 120 row(s). 120 skipped: no device name or IP address column was recognised (columns in the file: Serial, Owner).

Point-in-time imports

CSV / JSON

For a scanner without an API, or any export you can turn into rows. Configuration: assets_file, vulns_file, kb_file (any of them), and *_field options to map your own column names (hostname_field, ip_field, vuln_id_field, severity_field, cvss_field, cve_field, component_field, component_version_field, and others). Columns by default:

• Assets: ip_address, hostname, fqdn, os.
• Vulnerabilities: vuln_id and ip_address or asset_id (required); severity, title, cvss_base, cwe_ids, file_path, line_number, component_name, component_version (optional).
• Knowledge base: vuln_id, title (required); diagnosis, solution, cve_ids, cwe_ids (optional).

SARIF (Semgrep, CodeQL, Trivy, Grype, Snyk, Bandit, ESLint)

Reads: one SARIF 2.1.0 file per sync; one asset per repository or application. For software-composition results it records the package and version (from result properties, or from the message Trivy and Grype write), which is what fills Software Inventory. Configuration: sarif_file, optionally repo_name (the asset's name; defaults to the file name).

ASFF (AWS Security Hub, Inspector, GuardDuty)

Reads: a Security Hub findings export; one asset per AWS resource, with the vulnerable package Inspector names. Configuration: asff_file.

Penetration test

Reads: a tester's findings export (JSON or CSV) as one engagement. Fields: title, severity (or risk, rating), cvss, cvss_vector, cve_ids, cwe, targets (or target, affected, host), description, impact, recommendation, evidence. Configuration: pentest_file, engagement_name, tester. A PDF or Word report goes through the Penetration tests page instead, where each finding read from the prose is a proposal a person accepts.

Bug bounty (HackerOne, Bugcrowd, Intigriti)

Reads: a JSON export of reports, or HackerOne's and Bugcrowd's own API JSON. Fields: id, title, description, severity, state, target, cve_ids. Configuration: bugbounty_file.

Exposure

EASM import (Shodan, Censys, runZero, your own scans)

Reads: a JSON ({"exposures": [...]} or a bare array) or CSV file of internet exposures. Fields: ip (or exposed_ip), hostname, port (or exposed_port), service, technology, title (or finding_title), severity, last_seen, resolved_at. Each exposure is matched to an existing asset by IP first. Configuration: easm_file.

Patrowl

Two editions, chosen by the address:

• Patrowl EASM (cloud). Leave base_url empty, or set it to https://dashboard.cloud.patrowl.io. PYXA reads the Dashboard API: organizations (/api/auth/orgs/, the connection test), assets (/api/auth/assets/) and vulnerabilities (/api/auth/vulns/), following each list's next page.
• PatrowlManager (self-hosted, open source). Set base_url to the manager. PYXA reads /assets/api/v1/list and /findings/api/v1/list.

Configuration: api_key (Patrowl Dashboard > Account > API Token, sent as Authorization: Token), base_url as above, and for the cloud an optional org_id to read one organization instead of every one the token can see. Mapping (cloud): each vulnerability becomes an exposure on its asset, titled with Patrowl's id (for example TLS 1.0 enabled (V-10)). Severity is Patrowl's 0 to 4 scale (Info to Critical). patched and every closed-* status resolve the exposure. An asset Patrowl marks internal or restricted is not counted as internet-facing. Limit: an exposure raises risk on the matching host; it never sets a finding to Verified. Patrowl's CVSS and exploit detail is kept in the raw record but not imported as findings.

watchTowr

Configuration: base_url, api_key (Settings, API Management in the watchTowr dashboard). Limit: findings on domains, subdomains and IPs are imported; other asset types are skipped and logged rather than guessed at.

SecurityScorecard

Configuration: api_key, and either portfolio_id or a list of domains. Limit: one finding per factor and issue type, as SecurityScorecard's own dashboard leads with; per-instance issue detail is not imported.

Attack paths

BloodHound CE (API)

Crown jewels from Tier Zero. Every BloodHound sync marks the hosts whose computer BloodHound counts as Tier Zero (domain controllers and the like). A Tier Zero host is a crown jewel and is scored as criticality 5 of 5, whatever its tags; the asset page says Tier Zero in BloodHound. It is reset when the host leaves Tier Zero. This applies to the SharpHound import too.

Needs: an API token (Token ID and Token Key) from BloodHound, under My Profile, API Tokens. Configuration: host (for example https://bloodhound.example.com:8080), token_id, token_key. For BloodHound Enterprise, use the connector below.

BloodHound Enterprise

Reads: the tenant's attack path findings (GET /api/v2/attack-paths/findings), active, in progress and accepted, and its domains and Entra ID tenants (GET /api/v2/available-domains), as SpecterOps' published API specification documents them. Files: one asset per domain or tenant, the directory a finding is fixed in, and one finding per BloodHound Enterprise finding and its principals ("GenericWrite Privileges on Tier Zero Objects: Alice to Domain Admins"), with BloodHound's severity. Proves: its own findings. One the tenant no longer reports for a collected domain closes; a domain not collected keeps its findings. Does not read: which hosts sit on a path. Enterprise publishes findings, not the graph, so hosts' attack-path standing comes from a BloodHound CE or SharpHound source. Accepted in BloodHound Enterprise stays open in PYXA, with that status in its detail, until an exception is approved in PYXA. Needs: an API token (Token ID and Token Key), under My Profile, API Tokens in the tenant. Configuration: host (for example https://corp.bloodhoundenterprise.io), token_id, token_key.

SharpHound import

Reads: a folder of SharpHound output, unzipped JSON files or the collection zip (sharphound.exe -c All). Configuration: bloodhound_dir (a folder inside the import folder).

Inventory

ServiceNow CMDB

Reads: computers from cmdb_ci_computer (servers included), retired items left out, with owner, support group, location, department, company, business unit and environment as tags. Asset assignment maps those tags to units and owners. Proves: nothing about vulnerabilities. It merges with the scanners' assets by host name and address; a computer it lists that no scanner reached is counted as unscanned, shown as unknown and left out of percentages. Needs: an integration user with read access to the table (cmdb_read, or an ACL). Configuration: base_url, username, password; optionally table, query (an encoded query, for example operational_status=1), criticality_field and service_field: computers carry no business criticality or service by default, so name the instance's own fields (for example u_business_criticality). ServiceNow's choice list 1 - most critical to 4 - not critical reads as 5 to 2. Applies to the asset: the owner (owned_by, matched by its email), the criticality and business service when those fields are set, and the environment. See What a CMDB sets on an asset.

CMDB import (GLPI, iTop, Lansweeper, NetBox, a spreadsheet)

Reads: a CSV (comma, semicolon or tab) or JSON export of a CMDB's computers, one row per computer. Send it with an upload key or place it in the import folder (file-push.md). Proves: nothing about vulnerabilities, as for ServiceNow: a listed computer no scanner reached reads unknown, never clean. Configuration: cmdb_file; optionally tag_columns, the columns kept as tags (default location, support_group, department, company, business_unit, managed_by, environment). Columns, matched without regard to case, spaces or dashes; the first one present wins:

A row needs a host name, an FQDN or an address; a row with none is counted and skipped. Criticality is 1 (lowest) to 5 (highest), or a word: mission critical/critical 5, high 4, medium/moderate 3, low 2, minimal/none 1. A value outside those is ignored.

Name;IP address;Owner;Owner email;Business criticality;Business service;Environment;Location
app-01.example.com;10.20.0.15;Payments lead;payments.lead@example.com;Mission critical;Payments;Production;Paris

What a CMDB sets on an asset

Both CMDB connectors apply what they read to the asset each computer merges into, after the merge, so the scanners' host gains it:

Plan host filters and Asset assignment read the two attributes. A value the CMDB gives replaces PYXA's at each sync; a value it leaves empty changes nothing; an attribute a person set (manual override) is never replaced. A criticality typed on the asset page is replaced at the next sync when the CMDB names one, since the CMDB is the system of record.

Software inventory

The Software Inventory page lists the packages that vulnerability detections name, with their versions and the hosts or repositories that carry them. It fills from composition scanners:

• SARIF from Trivy, Grype or Snyk (trivy fs --format sarif, grype <image> -o sarif, snyk test --sarif);
• ASFF from AWS Inspector, through a Security Hub export;
• CSV with a component and version column (component_name, component_version, or your own names mapped in the connector).

Limit: it is not a list of every installed program. A package no scanner reports a vulnerability in does not appear. Defender and Spotlight add the packages they report vulnerable; PYXA holds no full software inventory from SCCM, Intune or a CMDB.

Ticketing

Configured under Administration, Ticketing. A plan opens one ticket; PYXA reads its status back and closes it when a verifying scan proves the plan done.

GLPI

PYXA speaks either GLPI API, selected per installation:

Which to choose. On GLPI 11, the High-Level API is the one GLPI now develops, and an instance may switch the legacy API off. Use v1 for GLPI 10 and earlier. GLPI documents the Password grant for scripts; a client-credentials token does not yet carry general API rights, so the account the tickets are opened as needs a profile with ticket rights (create, read, update) in the target entity. The entity ID, when set, is sent as the GLPI-Entity header (v2) or the ticket's entities_id (v1).

Common errors (v2): GLPI rejected the OAuth client (client ID or secret); not allowed the api scope; does not allow the Password grant; has no right to do this (the account's profile, ERROR_RIGHT_MISSING); No High-Level API at that address (GLPI 10 or earlier, or the base URL includes /api.php).

Generated from docs/connectors.md in the PYXA repository.