Configure Zero-touch API Based Scan
Click here to see this page in full context

 

Configure API-based Assessment

TotalCloud FlexScan's API-Based Assesment uses the APIs of AWS to collect OS package inventory from the workloads for vulnerability analysis. This agentless scan is a quick way to catch vulnerabilities that may pop-up in between the intervals where the agents wait to perform the next automated scan. When combined with agent scans, API-based scans offer a complete security solution by ensuring your newly introduced assets are secure without waitng for the Qualys agent scan.

 

Note: API-based scans are available for both CloudView and AssetView connectors. 

 

The below AWS configurations are required from the customer to enable API based assessment on TotalCloud. You can enable zero-touch API-based scan to perform vulnerability assessments on your new assets with cloud native APIs. The below configurations allow Qualys to listen to changes in the instance states and pass the running instance data to run scans.

Prerequisites for API-based Scan

•    Qualys Cloud Platform subscription with active TotalCloud subscription.
•    Enable Zero-touch API Based Scan to your subscription from Qualys Backoffice. Contact your Qualys technical account manager (TAM) for enabling it.
•    AWS EC2 instances that report the inventory to AWS SSM.
•    AWS EventBridge configurations.

OS Compatibility

The following section lists the OS versions and supported platforms for Qualys Zero Touch API Based Assessment. Refer to API-Based Assessment OS Compatibility.

Configure AWS SSM Inventory

The SSM inventory must be configured to capture the instance data to perform scans. The SSM agent can be configured in selected regions or all regions. Follow the below steps to configure for either setting.

 

For Selected RegionsFor Selected Regions

1. Login to AWS Console and navigate to AWS Systems Manager.

2. Click Inventory > Setup Inventory.

3. Keep the default settings and click Setup Inventory.

The region presently active in the AWS account will be selected as the region where all managed instances are fetched. 

For All RegionsFor All Regions

 

1. Login to AWS console and navigate to AWS Systems Manager.

2. Click Quick Setup > Create.

 

 

3. In Host management > Click Create.

 

4. Go to 'Configuration options'.

5. Under Systems manager, select 'Collect inventory from your instances every 30 minutes'.

6. Under Targets, you can either choose between deploying to the current Region or a custom set of regions.

7. Choose regions.

8. Choose how you want to target instances. Let's select 'All instances'.

 

9. Next, under Target Regions.

10. Select 'All Regions'.

11. Click Create.

Configure EventBridge

Once the SSM agent is installed to collect instance data, we configure the EventBridge to listen to changes in instance state.

There are two ways of configuring EventBridge. Either manually from the AWS console or by uploading a CloudFormation template. Let us go through both methods below.

 

Manually via AWS ConsoleManually via AWS Console

Follow the below steps to enable your cloud events to reach the Qualys platform.

 

API Destination Connection

  1. Login to AWS Console and navigate to Amazon EventBridge.

  2. Click Integrations > API destinations > Connections tabs > Create Connection.

  3. Next, enter the connection name and Description.

  4. Under 'Authorization', select Destination type as 'Others'.

  5. Selection Authorization type as 'API Key'.

  6. Enter API Key name and Value.

  7. Under 'Invocation Http Parameters', provide the parameter, key and value.

  8. Generate Auth token by running the below command.

  9. curl --location --request POST 'https://< API Gateway URL >/auth' --header 'Content-Type: application/x-www-form-urlencoded' --data-urlencode 'username=<QualysUsername> --data-urlencode 'password=<QualysPassword>'--data-urlencode 'token=true'

  10. Generate Subscription token by running the below command.

  11. curl --location --request POST 'https://< API Gateway URL >/qas/subscription-token' --header 'Content-Type: application/json' --header 'Authorization: Bearer <Auth Token> --data-raw '{ "expiry": 500000}' 

  12.  Click Create.

Now that the connection to the destination has been authorized, we must provide the Qualys API endpoint as the destination to establish the EventBridge connection.

 

API Destination

  1. Click Integrations -> API destinations -> API destinations tabs -> Create API Destination

  2. API Destination details.

  3. Enter Name and Description.

  4. Enter the API destination URL: <qualys_platform_url>/qflow/aws-eb, 

  5. Select HTTP Method as POST.

  6. Select Connection as 'Use an existing connection'.

  7. Select the API Destination Connection created above.

 

Now, we configure the Rules so that EventBridge knows what to listen to before passing the information to Qualys. In this case, we set the Rule to listen to changes in Instance states. Specifically, the event is alerted when instances are switched to running states.

 

Rules

  1. Click Events -> Rules -> Create Rule 

  2. Rule details.

  3. Enter Name and Description.

  4. Select Event bus as 'Default'.

  5. Select Rule Type as 'Rule with an event pattern'.

  6. Click Next.

  7. Event pattern.

  8. Select Event Source as AWS Services.

  9. Select AWS service as EC2.

  10. Select Event type as 'EC2 Instance State-change Notification'.

  11. Select Specific state(s) as running.

  12. Click Next.

  13. Select targets 

  14. Select Target types as 'EventBridge API destination'.

  15. Select API destination as 'Use an existing API destination' (Select the API destination which was created as part of the API Destination).

  16. Select Execution role as 'Create a new role for this specific resource'.

  17. Click Next.

  18. Under Tags, configure tags if required.

  19. Click Next.

  20. Click Review and create.

  21. Click Create Rule.

 

Using AWS CloudFormation TemplateUsing AWS CloudFormation Template

 

  1. Login to AWS Console and navigate to CloudFormation. 

  2. Stack > Create Stack > With new resources (standard).

  3. In 'Specify template', upload the template file (Note: You can download the CloudFormation template file from here.).

  4. Click Next.

  5. Under Specify stack details, provide Stack name.

  6. In APIGatewayURL parameter, provide the Qualys API Gateway URL. Find the Gateway URL at https://www.qualys.com/platform-identification/ 

  7. Generate Auth token by running the below command.

  8. curl --location --request POST 'https://< API Gateway URL >/auth' --header 'Content-Type: application/x-www-form-urlencoded' --data-urlencode 'username=<QualysUsername> --data-urlencode 'password=<QualysPassword>'--data-urlencode 'token=true'

  9. Generate Subscription token by running the below command.

  10. curl --location --request POST 'https://< API Gateway URL >/qas/subscription-token' --header 'Content-Type: application/json' --header 'Authorization: Bearer <Auth Token> --data-raw '{ "expiry": 500000}' 

  11. Provide the Subscription oken and click next.

  12. Keep the default settings in step 3 and step 4.

  13. Click Next > Submit.

Run API-Based Scan

Navigate to Configure FlexScan, select a connector, and click Configure FlexScan. Choose the API-Based Scan Scan and click Configure.

Make sure to select the "Modifying the settings now..." checkbox to agree to the possible overwriting of existing FlexScan configurations. 

Additional Information

Connector permissions to be added for API-based Assessment. Provide these permissions in your AWS console. 

 

Create a policy that includes the permissions:

 

Refer to the following link to learn how to provide cross-account role access by creating an IAM role. Learn more.

Related Topics

Configure FlexScan

Configure Qualys Agent Scan