Qualys Cloud Agent Kubernetes Bootstrapper

A Kubernetes-native solution for deploying Qualys Cloud Agent across all nodes in a cluster. The bootstrapper automatically detects host operating system and architecture, then installs the appropriate agent package.

Architecture

flowchart TB
    subgraph k8s["Kubernetes Cluster"]
        subgraph cp["Control Plane"]
            DS[DaemonSet Controller]
        end

        subgraph secrets["Configuration"]
            SEC[Secret]
            CM[ConfigMap]
        end

        subgraph nodes["Worker Nodes"]
            subgraph n1["Node 1 - Ubuntu x64"]
                P1[Pod] --> A1[Qualys Agent]
            end
            subgraph n2["Node 2 - RHEL ARM64"]
                P2[Pod] --> A2[Qualys Agent]
            end
            subgraph n3["Node 3 - Amazon Linux"]
                P3[Pod] --> A3[Qualys Agent]
            end
        end
    end

    subgraph qualys["Qualys Cloud"]
        API[Platform API]
    end

    DS --> P1 & P2 & P3
    SEC & CM --> P1 & P2 & P3
    A1 & A2 & A3 --> API

Loading

Features

• Universal Compatibility: Ubuntu, Debian, RHEL, CentOS, Fedora, Amazon Linux, CoreOS, SUSE
• Multi-Architecture: Single image supports x86_64 and ARM64
• Kubernetes-Native: DaemonSet deployment with Secrets management
• Secure by Design: Credentials never logged, minimal host access
• Idempotent: Safe to restart, reschedule, or scale

Quick Start

flowchart LR
    A[Download Packages] --> B[Build Image]
    B --> C[Configure Secrets]
    C --> D[Deploy DaemonSet]
    D --> E[Verify]

Loading

1. Download Agent Packages

./download-packages.sh

2. Build Container Image

./build.sh v2.1.0

3. Configure Credentials

./manage-secrets.sh

4. Deploy

kubectl apply -f k8s/daemonset.yaml

5. Verify

kubectl get pods -n qualys -o wide
kubectl logs -n qualys -l app=qualys-cloud-agent

Installation Flow

stateDiagram-v2
    [*] --> CheckAgent
    CheckAgent --> Running: Already installed
    CheckAgent --> Detect: Not installed
    Running --> Sleep

    Detect --> SelectPackage
    SelectPackage --> Install
    Install --> Configure
    Configure --> StartService
    StartService --> Activate
    Activate --> Sleep
    Sleep --> [*]

Loading

Project Structure

qualys-cloudagentbuilder/
├── Dockerfile                    # Container image
├── install.sh                    # Host installation script
├── build.sh                      # Multi-arch build script
├── download-packages.sh          # Qualys API downloader
├── manage-secrets.sh             # Kubernetes secrets manager
├── k8s/
│   └── daemonset.yaml           # Kubernetes manifests
├── helm/
│   └── qualys-agent/            # Helm chart
└── docs/
    └── blog-technical-architecture.md

Supported Platforms

flowchart TD
    subgraph deb["DEB Packages"]
        Ubuntu[Ubuntu 18.04+]
        Debian[Debian 10+]
    end

    subgraph rpm["RPM Packages"]
        RHEL[RHEL 7+]
        CentOS[CentOS 7+]
        Amazon[Amazon Linux 2]
        Fedora[Fedora]
        CoreOS[CoreOS/Flatcar]
        SUSE[SUSE/openSUSE]
    end

    subgraph arch["Architectures"]
        x64[x86_64 / amd64]
        arm[ARM64 / aarch64]
    end

    deb --> arch
    rpm --> arch

Loading

Qualys POD Identifiers

POD	Region	API URL
US1	United States 1	qualysapi.qualys.com
US2	United States 2	qualysapi.qg2.apps.qualys.com
US3	United States 3	qualysapi.qg3.apps.qualys.com
US4	United States 4	qualysapi.qg4.apps.qualys.com
EU1	European Union 1	qualysapi.qualys.eu
EU2	European Union 2	qualysapi.qg2.apps.qualys.eu
EU3	European Union 3	qualysapi.qg3.apps.qualys.it
IN1	India	qualysapi.qg1.apps.qualys.in
CA1	Canada	qualysapi.qg1.apps.qualys.ca
AE1	UAE	qualysapi.qg1.apps.qualys.ae
UK1	United Kingdom	qualysapi.qg1.apps.qualys.co.uk
AU1	Australia	qualysapi.qg1.apps.qualys.com.au
KSA1	Saudi Arabia	qualysapi.qg1.apps.qualysksa.com

Security

flowchart LR
    subgraph protection["Security Controls"]
        PSS[Pod Security Standards]
        NP[Network Policy]
        RBAC[Minimal RBAC]
        SEC[Encrypted Secrets]
    end

    subgraph access["Host Access"]
        MM[Minimal Mounts]
        NS[nsenter]
    end

    subgraph excluded["Not Mounted"]
        HOME[/home]
        ROOT[/root]
        FULL[Full /]
    end

    protection --> access
    access -.->|excluded| excluded

Loading

• Pod Security Standards: Namespace with privileged PSS labels
• Network Policy: Egress restricted to HTTPS (443) and DNS (53)
• Minimal Mounts: Targeted paths, not full filesystem
• Credential Protection: Secrets never logged, config files mode 600
• RBAC: Read-only node/pod access

Helm Installation

helm install qualys-agent ./helm/qualys-agent \
  --namespace qualys \
  --create-namespace \
  --set credentials.activationId="YOUR_ACTIVATION_ID" \
  --set credentials.customerId="YOUR_CUSTOMER_ID" \
  --set config.serverUri="https://qagpublic.qg1.apps.qualys.com/CloudAgent/"

Configuration

Required Settings

Variable	Source	Description
ACTIVATION_ID	Secret	Qualys activation ID
CUSTOMER_ID	Secret	Qualys customer ID
SERVER_URI	ConfigMap	Qualys platform endpoint

Optional Settings

Variable	Source	Default	Description
LOG_LEVEL	ConfigMap	3	Log verbosity (0=fatal, 5=trace)
LOG_FILE_DIR	ConfigMap	/var/log/qualys/	Log directory
LOG_DEST_TYPE	ConfigMap	file	file or syslog
CMD_MAX_TIMEOUT	ConfigMap	1800	Command timeout (seconds)
PROCESS_PRIORITY	ConfigMap	0	Nice value (-20 to 19)
SCAN_DELAY_VM	ConfigMap	0	VM scan delay (0-43200s)
SCAN_DELAY_PC	ConfigMap	0	PC scan delay (0-43200s)
USE_SUDO	ConfigMap	0	Run with sudo (0 or 1)
USE_AUDIT_DISPATCHER	ConfigMap	0	FIM with auditd (0 or 1)

Proxy Settings

Variable	Source	Description
QUALYS_HTTPS_PROXY	Secret	Proxy for Qualys traffic only
HTTPS_PROXY	Secret	System-wide proxy
PROXY_FAIL_OPEN	ConfigMap	Attempt direct on proxy failure (0 or 1)
QUALYS_PROXY_ORDER	ConfigMap	sequential or random
CA_CERT_BUNDLE	Secret	Custom CA cert (base64 encoded)

Proxy URL format: https://[username:password@]host[:port]

Build Options

Flag	Description
--download	Download packages from Qualys API
--skip-existing	Skip existing package files
--no-push	Build locally without pushing

Troubleshooting

# Check pod status
kubectl describe pod -n qualys <pod-name>

# View installation logs
kubectl logs -n qualys <pod-name>

# Verify agent on host
kubectl exec -n qualys <pod-name> -- \
  nsenter --target 1 --mount --uts --ipc --net --pid -- \
  systemctl status qualys-cloud-agent

Documentation

See docs/blog-technical-architecture.md for detailed architecture and deployment patterns.

License

MIT License