GRCLANKER / qualys-sec-inspector

Qualys Security Inspector

Qualys · Vulnerability & Application Security

VENDOR: Qualys LANG: go UPDATED: 2026-03-29

qualys-sec-inspector

1. Overview

A security compliance inspection tool for the Qualys Cloud Platform that audits vulnerability management configurations, policy compliance profiles, scan coverage, asset group hygiene, authentication records, scanner appliance status, and cloud connector settings. The tool connects to Qualys VM, PC, WAS, GAV, CSAM, and CloudView APIs to evaluate scan scheduling discipline, asset coverage completeness, credential scan ratios, vulnerability SLA adherence, and agent deployment status. Results are output as structured compliance reports mapped to FedRAMP, CMMC, SOC 2, CIS, PCI-DSS, STIG, IRAP, and ISMAP controls.

2. APIs & SDKs

Qualys APIs

API	Base URL	Purpose
VM API v2	`https://qualysapi.{platform}/api/2.0/fo/`	Vulnerability management: scans, reports, assets
VMDR API	`https://qualysapi.{platform}/qps/rest/2.0/`	Vulnerability management, detection, and response
PC API	`https://qualysapi.{platform}/api/2.0/fo/compliance/`	Policy compliance scanning and reporting
WAS API	`https://qualysapi.{platform}/qps/rest/3.0/`	Web application scanning
GAV API	`https://qualysapi.{platform}/qps/rest/2.0/`	Global AssetView (unified asset inventory)
CSAM API	`https://qualysapi.{platform}/qps/rest/2.0/`	CyberSecurity Asset Management
CloudView API	`https://qualysapi.{platform}/cloudview-api/rest/v1/`	Cloud security posture (AWS, Azure, GCP)
User API	`https://qualysapi.{platform}/msp/`	User and subscription management

Platform URLs

Platform	API Server
US Platform 1	`qualysapi.qualys.com`
US Platform 2	`qualysapi.qg2.apps.qualys.com`
US Platform 3	`qualysapi.qg3.apps.qualys.com`
EU Platform 1	`qualysapi.qualys.eu`
EU Platform 2	`qualysapi.qg2.apps.qualys.eu`
India	`qualysapi.qg1.apps.qualys.in`
Canada	`qualysapi.qg1.apps.qualys.ca`
UAE	`qualysapi.qg1.apps.qualys.ae`
Australia	`qualysapi.qg1.apps.qualys.com.au`

Key API Endpoints

Vulnerability Management (VM API v2):

POST /api/2.0/fo/scan/ — Launch, list, and manage vulnerability scans
POST /api/2.0/fo/scan/compliance/ — Launch and manage compliance scans
GET /api/2.0/fo/schedule/scan/ — List scheduled scan tasks
POST /api/2.0/fo/asset/host/ — List and manage host assets
GET /api/2.0/fo/asset/group/ — List asset groups and membership
POST /api/2.0/fo/asset/ip/ — IP address tracking and assignment
GET /api/2.0/fo/report/ — List and download reports
GET /api/2.0/fo/scan/option_profile/ — List option profiles (scan configs)
GET /api/2.0/fo/auth/ — List authentication records (credentialed scanning)
GET /api/2.0/fo/appliance/ — List scanner appliances and status
GET /api/2.0/fo/user/ — List user accounts and roles
GET /api/2.0/fo/activity_log/ — Audit activity log

VMDR / Qualys Query Service (QPS):

POST /qps/rest/2.0/search/am/hostasset — Search host assets with QQL
POST /qps/rest/2.0/search/was/webapp — Search web applications
GET /qps/rest/2.0/count/am/hostasset — Count assets matching criteria

Policy Compliance (PC API):

GET /api/2.0/fo/compliance/policy/ — List compliance policies
GET /api/2.0/fo/compliance/posture/info/ — Policy compliance posture
GET /api/2.0/fo/compliance/control/ — List compliance controls

Web Application Scanning (WAS API):

POST /qps/rest/3.0/search/was/webapp — List web applications
POST /qps/rest/3.0/search/was/wasscan — List WAS scan results
POST /qps/rest/3.0/search/was/finding — List WAS findings

CloudView API:

GET /cloudview-api/rest/v1/aws/connectors — AWS cloud connectors
GET /cloudview-api/rest/v1/azure/connectors — Azure cloud connectors
GET /cloudview-api/rest/v1/gcp/connectors — GCP cloud connectors
GET /cloudview-api/rest/v1/evaluations — Cloud resource evaluations

SDKs

SDK	Language	Package
qualysapi	Python	`pip install qualysapi` (community)
pyqualys	Python	Community wrapper for Qualys APIs
qualyspy	Python	Community library for VM/PC APIs
Qualys CLI	CLI	Qualys provides limited CLI tooling

3. Authentication

Basic Authentication

The primary authentication method for Qualys APIs v1/v2:

Authorization: Basic base64(username:password)

OAuth 2.0 Bearer Token

For newer APIs (VMDR, GAV, CSAM):

# Token request
curl -X POST "https://qualysapi.qualys.com/auth" \
  -d "username=USER&password=PASS&token=true"

# Returns JWT bearer token valid for 4 hours
Authorization: Bearer <jwt_token>

Required Permissions

The API user account must have:

Manager or Unit Manager role (for full configuration visibility)
Access to all subscribed modules (VM, PC, WAS, GAV, CloudView)
Permission to view all asset groups and scan schedules
Access to user management APIs (for role auditing)

Configuration

QUALYS_USERNAME=api_user
QUALYS_PASSWORD=...
QUALYS_PLATFORM=qualysapi.qualys.com
QUALYS_USE_OAUTH=true

4. Security Controls

Scan schedule coverage — Verify all asset groups have recurring vulnerability scans scheduled; flag groups with no active schedule or schedules older than 30 days
Authenticated scan ratio — Calculate the percentage of hosts scanned with credentials vs. unauthenticated; flag environments below 80% credentialed scan rate
Scan option profile review — Audit option profiles for aggressive vs. safe scan settings; verify profiles match environment requirements (internal vs. external)
Asset group completeness — Compare Qualys asset inventory against known CMDB/network ranges; flag unmonitored IP ranges and orphaned assets
Cloud connector status — Verify AWS, Azure, and GCP cloud connectors are active and successfully syncing; flag disconnected or erroring connectors
Scanner appliance health — Audit scanner appliance status (connected, heartbeat recency, version currency); flag offline or outdated appliances
Agent deployment coverage — Calculate Cloud Agent deployment coverage across asset inventory; flag asset groups with low agent penetration
Authentication record completeness — Verify authentication records exist for all target OS types (Windows, Linux, network devices); flag expired or failing credentials
Policy compliance profile assignment — Verify compliance policies are assigned to appropriate asset groups; flag unassigned or draft policies
Vulnerability SLA adherence — Audit open vulnerabilities against defined SLA windows (critical: 15 days, high: 30 days, medium: 90 days); calculate SLA compliance percentage
Patch management tracking — Verify patch availability tracking is enabled; audit patch age for open vulnerabilities
Report template and distribution — Verify automated report generation is configured; audit report distribution lists for appropriate recipients
User role and permission audit — Enumerate all Qualys user accounts and roles; flag inactive users, shared accounts, and excessive Manager-role assignments
External scanner configuration — Verify external perimeter scans are configured from Qualys external scanners; audit external scan frequency
Web application inventory — Audit WAS web application inventory completeness; flag web apps without recent scans or with stale authentication
Exclusion list review — Audit scan exclusion lists (excluded IPs, hosts, QIDs); flag overly broad exclusions that reduce coverage
Vulnerability prioritization (VPR/QDS) — Verify Qualys Detection Score (QDS) or CVSS-based prioritization is active; audit triage workflow
Tag-based asset management — Verify asset tagging strategy is implemented; audit tag coverage for compliance scope identification
Activity log monitoring — Verify activity log retention and review; flag sensitive admin actions (user creation, policy changes, scan deletions)
Network segmentation scanning — Verify separate scan schedules exist for different network segments (DMZ, internal, OT/ICS); flag flat scanning architectures

5. Compliance Framework Mappings

#	Control	FedRAMP	CMMC	SOC 2	CIS	PCI-DSS	STIG	IRAP	ISMAP
1	Scan schedule coverage	RA-5	3.11.2	CC7.1	7.1	11.3.1	SRG-APP-000516	ISM-1163	CPS.RA-5
2	Authenticated scan ratio	RA-5(1)	3.11.2	CC7.1	7.2	11.3.2	SRG-APP-000516	ISM-1163	CPS.RA-5
3	Scan option profile review	RA-5(2)	3.11.1	CC7.1	7.3	11.3.1	SRG-APP-000516	ISM-1163	CPS.RA-5
4	Asset group completeness	CM-8	3.4.1	CC6.1	1.1	2.4	SRG-APP-000383	ISM-1599	CPS.CM-8
5	Cloud connector status	CM-8(2)	3.4.1	CC6.1	—	2.4	SRG-APP-000383	ISM-1599	CPS.CM-8
6	Scanner appliance health	SI-2(2)	3.14.1	CC7.1	—	11.3.1	SRG-APP-000456	ISM-1163	CPS.SI-2
7	Agent deployment coverage	CM-8(1)	3.4.1	CC6.1	1.1	2.4	SRG-APP-000383	ISM-1599	CPS.CM-8
8	Auth record completeness	RA-5(5)	3.11.2	CC7.1	7.2	11.3.2	SRG-APP-000516	ISM-1163	CPS.RA-5
9	Policy compliance assignment	CM-6(1)	3.4.2	CC8.1	4.1	2.2.1	SRG-APP-000384	ISM-1624	CPS.CM-6
10	Vulnerability SLA adherence	RA-5(3)	3.11.2	CC7.1	7.4	6.1	SRG-APP-000456	ISM-1690	CPS.RA-5
11	Patch management tracking	SI-2	3.14.1	CC7.1	7.5	6.3.3	SRG-APP-000456	ISM-1143	CPS.SI-2
12	Report template/distribution	RA-5(4)	3.11.3	CC7.2	—	11.3.4	SRG-APP-000516	ISM-0109	CPS.RA-5
13	User role/permission audit	AC-6(5)	3.1.5	CC6.3	—	7.1.1	SRG-APP-000340	ISM-1507	CPS.AC-6
14	External scanner config	RA-5	3.11.2	CC7.1	—	11.3.1	SRG-APP-000516	ISM-1163	CPS.RA-5
15	Web app inventory	RA-5(3)	3.11.2	CC7.1	—	6.4.1	SRG-APP-000516	ISM-1163	CPS.RA-5
16	Exclusion list review	RA-5(2)	3.11.1	CC7.1	7.3	11.3.1	SRG-APP-000516	ISM-1163	CPS.RA-5
17	Vulnerability prioritization	RA-5(3)	3.11.1	CC7.1	7.6	6.1	SRG-APP-000456	ISM-1690	CPS.RA-5
18	Tag-based asset management	CM-8(5)	3.4.1	CC6.1	1.1	2.4	SRG-APP-000383	ISM-1599	CPS.CM-8
19	Activity log monitoring	AU-6	3.3.5	CC7.2	8.2	10.6.1	SRG-APP-000516	ISM-0580	CPS.AU-6
20	Network segmentation scanning	RA-5	3.11.2	CC7.1	—	11.3.1	SRG-APP-000516	ISM-1163	CPS.RA-5

6. Existing Tools

Tool	Description	Limitations
Qualys Console	Built-in web UI for configuration and reporting	Manual review; no automated compliance posture assessment of Qualys itself
Qualys API Documentation	Comprehensive API reference	Reference only, no pre-built audit tooling
ScoutSuite	Multi-cloud security auditing	Cloud-focused; no Qualys platform configuration audit
qualysapi (Python)	Community Python wrapper	API wrapper only, no security compliance logic
Qualys VMDR Dashboard	Built-in vulnerability management dashboard	Focuses on vulnerability findings, not scan program health
CISA BOD 23-01	Federal vulnerability scanning requirements	Requirements reference only, no Qualys-specific tooling

Gap: No open-source tool audits the health and compliance posture of a Qualys deployment itself (scan coverage, credential hygiene, appliance health, user roles). Existing tools focus on consuming Qualys vulnerability data, not evaluating whether the Qualys scanning program meets compliance requirements.

7. Architecture

qualys-sec-inspector/
├── cmd/
│   └── qualys-sec-inspector/
│       └── main.go                  # CLI entrypoint
├── internal/
│   ├── client/
│   │   ├── vm.go                    # VM API v2 client
│   │   ├── qps.go                   # QPS/VMDR REST client
│   │   ├── pc.go                    # Policy Compliance API client
│   │   ├── was.go                   # WAS API client
│   │   ├── cloudview.go             # CloudView API client
│   │   ├── auth.go                  # Authentication (Basic + OAuth)
│   │   └── ratelimit.go             # Rate limiter (Qualys: 300 calls/hour default)
│   ├── analyzers/
│   │   ├── scanschedule.go          # Control 1: Scan schedule coverage
│   │   ├── authscan.go              # Control 2: Authenticated scan ratio
│   │   ├── optionprofile.go         # Control 3: Scan option profile review
│   │   ├── assetgroups.go           # Control 4: Asset group completeness
│   │   ├── cloudconnectors.go       # Control 5: Cloud connector status
│   │   ├── appliances.go            # Control 6: Scanner appliance health
│   │   ├── agents.go                # Control 7: Agent deployment coverage
│   │   ├── authrecords.go           # Control 8: Authentication record completeness
│   │   ├── policyassignment.go      # Control 9: Policy compliance profile assignment
│   │   ├── vulnsla.go               # Control 10: Vulnerability SLA adherence
│   │   ├── patching.go              # Control 11: Patch management tracking
│   │   ├── reports.go               # Control 12: Report template and distribution
│   │   ├── userroles.go             # Control 13: User role and permission audit
│   │   ├── externalscan.go          # Control 14: External scanner configuration
│   │   ├── webapps.go               # Control 15: Web application inventory
│   │   ├── exclusions.go            # Control 16: Exclusion list review
│   │   ├── prioritization.go        # Control 17: Vulnerability prioritization
│   │   ├── tagging.go               # Control 18: Tag-based asset management
│   │   ├── activitylog.go           # Control 19: Activity log monitoring
│   │   └── segmentation.go          # Control 20: Network segmentation scanning
│   ├── reporters/
│   │   ├── json.go                  # JSON output reporter
│   │   ├── csv.go                   # CSV output reporter
│   │   ├── markdown.go              # Markdown report with compliance matrix
│   │   ├── html.go                  # HTML dashboard report
│   │   └── sarif.go                 # SARIF format for CI/CD integration
│   ├── compliance/
│   │   ├── mapper.go                # Maps findings to framework controls
│   │   ├── fedramp.go               # FedRAMP control definitions
│   │   ├── cmmc.go                  # CMMC control definitions
│   │   ├── soc2.go                  # SOC 2 trust criteria
│   │   ├── cis.go                   # CIS Benchmark references
│   │   ├── pcidss.go                # PCI-DSS requirements
│   │   ├── stig.go                  # DISA STIG rules
│   │   ├── irap.go                  # IRAP ISM controls
│   │   └── ismap.go                 # ISMAP control references
│   ├── models/
│   │   ├── finding.go               # Finding severity, evidence, remediation
│   │   ├── control.go               # Security control definition
│   │   └── report.go                # Aggregate report model
│   └── tui/
│       ├── app.go                   # Bubble Tea TUI application
│       ├── views/
│       │   ├── dashboard.go         # Summary dashboard view
│       │   ├── controls.go          # Control detail drill-down
│       │   └── compliance.go        # Framework compliance matrix view
│       └── components/
│           ├── table.go             # Sortable findings table
│           ├── progress.go          # Scan progress indicator
│           └── severity.go          # Severity badge rendering
├── pkg/
│   └── version/
│       └── version.go               # Build version info
├── go.mod
├── go.sum
├── Makefile
├── Dockerfile
├── .goreleaser.yaml
└── spec.md

Key Dependencies

Package	Purpose
`github.com/spf13/cobra`	CLI framework
`github.com/charmbracelet/bubbletea`	Terminal UI framework
`github.com/charmbracelet/lipgloss`	TUI styling
`encoding/xml`	Qualys VM API v2 returns XML responses

8. CLI Interface

qualys-sec-inspector [command] [flags]

Commands:
  scan          Run security compliance scan against Qualys platform
  report        Generate compliance report from scan results
  version       Print version information

Global Flags:
  --username string     Qualys API username [$QUALYS_USERNAME]
  --password string     Qualys API password [$QUALYS_PASSWORD]
  --platform string     Qualys platform URL [$QUALYS_PLATFORM] (default "qualysapi.qualys.com")
  --oauth               Use OAuth bearer token instead of Basic auth
  --output string       Output format: json, csv, markdown, html, sarif (default "json")
  --output-dir string   Directory for report output (default "./results")
  --severity string     Minimum severity to report: critical, high, medium, low, info (default "low")
  --controls string     Comma-separated list of control numbers to run (default: all)
  --quiet               Suppress progress output
  --no-color            Disable colored output
  --tui                 Launch interactive terminal UI

Scan Flags:
  --skip-was            Skip Web Application Scanning checks
  --skip-cloudview      Skip CloudView connector checks
  --skip-pc             Skip Policy Compliance checks
  --sla-critical int    Critical vuln SLA in days (default 15)
  --sla-high int        High vuln SLA in days (default 30)
  --sla-medium int      Medium vuln SLA in days (default 90)
  --parallel int        Number of parallel API calls (default 2)
  --timeout duration    API call timeout (default 60s)

Examples:
  # Full platform audit with JSON output
  qualys-sec-inspector scan --username api_user --password ...

  # Scan coverage controls only
  qualys-sec-inspector scan --controls 1,2,4,7,8 --output markdown

  # Interactive TUI mode
  qualys-sec-inspector scan --tui

  # CI/CD pipeline with SARIF output
  qualys-sec-inspector scan --output sarif --severity high --skip-was

9. Build Sequence

# 1. Initialize module
go mod init github.com/ethanolivertroy/qualys-sec-inspector

# 2. Add dependencies
go get github.com/spf13/cobra
go get github.com/charmbracelet/bubbletea
go get github.com/charmbracelet/lipgloss

# 3. Build
go build -ldflags "-X pkg/version.Version=$(git describe --tags)" \
  -o bin/qualys-sec-inspector ./cmd/qualys-sec-inspector/

# 4. Test
go test ./...

# 5. Lint
golangci-lint run

# 6. Docker
docker build -t qualys-sec-inspector .

# 7. Release
goreleaser release --snapshot

10. Status

Not yet implemented. Spec only.

Download GitHub