Qualys Integration

🚧

Prerequisites

To call the List PC Scans endpoint (/api/2.0/fo/scan/compliance/?action=list) the user must:

• Log in as a Manager or similar level admin
• Be assigned appropriate scope (Business Unit / Asset Groups)
• Have a subscription that includes Policy Compliance (PC) and API access

Decide the Access Model

Pick what kind of access you want the integration to have:

• All assets (broad): Assign (or create) a role equivalent to Manager with API Access.

• Scoped access (recommended): Use Unit Manager (or a custom role) with API Access, and restrict to the relevant Business Unit and Asset Groups.

  Tip

  For automation, we recommend a dedicated service user with scoped access.

Create or Update a Role with API Access

1. In Qualys, go to Administration → Users → Role Management.
2. Create a New role or Edit an existing role used by the API user.
3. In Permissions:
   • Ensure API Access is enabled/checked.
   • Ensure Policy Compliance module permissions are enabled (e.g., View/Read compliance scan data; if you also launch scans, include Launch/Manage as needed).
4. Save the role.

If you’re using the built-in Manager or Unit Manager roles, confirm that API Access is allowed for that role. If not, create a Custom role cloned from it and add API Access.

Assign the Role to the User (and Scope)

1. Go to Administration → Users.
2. Select the user/service account you will use for API calls; click Edit.
3. Set Role to the role you created above.
4. If using scoping:
   • Set the Business Unit appropriately.
   • Under Asset Groups (or equivalent scope controls), select only the groups the API should see.
5. Save.

Confirm Subscription/API Settings

• Verify your subscription includes Policy Compliance and that API usage is permitted for your platform.

• Note your API base URL (varies by platform, e.g., https://qualysapi.qualys.com, https://qualysapi.qg2.apps.qualys.com, etc.).

  Your Qualys account page or admin typically provides this.

Verify with a Test Call

Use a least-privilege test account and run:

# Replace with your platform base URL and credentials

curl -u "USERNAME:PASSWORD" \
  "https://<your-qualys-api-base>/api/2.0/fo/scan/compliance/?action=list&status=Finished"

Expected results

• 200 OK with XML response containing <COMPLIANCE_SCAN_LIST_OUTPUT> and <SCAN> entries.
• If scoped, you’ll only see scans within the user’s assigned scope.

🚧

Prerequisites

• To call Get a List of Assets (GET /pm/v1/assets) you must enable PM API Access on a Qualys role assigned to the calling user/service account. This permission allows Patch Management users to make PM API calls. Instructions on assigning the PM API Permission are here.

  The endpoint returns assets enabled for Patch Management within the caller’s scope. See endpoint details and parameters here .

• Your subscription includes Patch Management (PM) and supports PM APIs

• You can sign in as an admin who can edit roles.

• You know the user’s scope (Business Unit / tags / asset groups) that should be visible via API. Role-based access and tags control what assets the user can view.

Decide the Access Model

Choose either:

• Broad access: A role with PM permissions and PM API Access for all needed assets.
• Scoped access (recommended): A role with PM API Access limited via Business Unit and/or tags/asset groups so the API only returns in-scope assets.

Enable PM API Access on a Role

1. In Qualys, open Administration → Users → Role Management.

2. Select the role (or create a new custom role) and click Edit.

3. Go to Permissions → Edit.

4. Expand PM Permissions and checkPM API Access.

5. Save.

   This explicitly allows users of that role to make Patch Management API calls.

Assign the Role and Scope to the API User

1. Go to Administration → Users and edit the user/service account used for API calls.
2. Set the Role to the one with PM API Access.
3. Configure scope (Business Unit and/or tags/asset groups) so returned assets match your intent.
4. Save.

Authenticate and Note your API Base URL

• PM APIs require authentication; obtain a JWT (token) via the Qualys authentication flow before calling PM endpoints. cdn2.qualys.com+1
• Use the correct regional API base URL for your platform (e.g., https://qualysapi.<region>.apps.qualys.com where <region> is replaced). Release notes and guides stress using the proper base.

The Unix auth-record API (/api/2.0/fo/auth/unix/) lets you create, update, list, and delete Unix authentication records used for authenticated scans.

To call it, the user/service account must have:

• API Access enabled for their role, and
• Authentication Record permissions (view/manage) in the VM/PC modules, within the intended asset scope.

🚧

Prerequisites

• Subscription includes Vulnerability Management (VM) and/or Policy Compliance (PC); API access is allowed for your platform/region.
• You can can edit roles (e.g., Manager) to grant permissions.

Choose the Access Model

• Broad access: Manager (all assets) + API Access.
• Scoped access (recommended): Unit Manager or custom role with API Access and auth-record permissions, limited by Business Unit / Asset Groups.

Enable Role Permissions

1. Go to Administration → Users → Role Management.
2. Edit the role (or Create a custom role).
3. In Permissions:
   1. Check API Access.
   2. Enable Authentication Record permissions for VM/PC:
      1. View Authentication Records
      2. Manage Authentication Records – Create, Update, Delete
   3. Optional: Control secrets in responses by disablingView Password in Authentication Record* to keep passwords masked when fetched via API.*
4. Save the role.

Assign Role & Scope to the API User

1. Go to Administration → Users → Edit the API user/service account.
2. Assign the role from above .
3. Set Business Unit and Asset Groups to the intended scope.