Configure API-based Assessment

Supported Cloud Providers:  

TotalCloud FlexScan's API-based assessment 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 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 waiting for the Qualys agent scan.

API-based scans are available for both CSPM and AssetView connectors. 

The below AWS configurations are required from the customer to enable API-based assessment on TotalCloud. With cloud-native APIs, you can enable zero-touch API-based scans to perform vulnerability assessments on your new assets. 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 full TotalCloud subscription.
•    Enable Zero-touch API-based Scan to your subscription from Qualys Backoffice. Contact your Qualys technical account manager (TAM) to enable 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 Scan 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 the instance state.

Before configuring the event bridge, you must generate a subscription token, which is required to grant permission to deploy the scan.

Generate a Subscription Token

Follow the steps below to generate a Subscription Token

  1. Generate Auth token by running the below command.

    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'
  2. Generate Subscription token by running the below command.

    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}'

  3. Store the Subscription Token for later use.

Next, 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 Console

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

API Destination ConnectionAPI Destination Connection

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

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

  3. Next, provide the connection name and Description.

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

  5. Selection Authorization type as 'API Key.' 

  6. Enter the API Key name and Value.

  7. Under 'Invocation Http Parameters', provide the parameter, key and value (refer to 'Generate a subscription token'). 

  8. 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.

RulesRules

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.

Define Rule detail

  1. Click Events -> Rules -> Create Rule. 

  2. Under 'Define rule detail', provide Name and Description.

  3. Select Event bus as 'Default'.

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

  5. Click Next.

Build Event Pattern

  1. Select Event Source as AWS Services.

  2. Select AWS service as EC2.

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

  4. Select the specific state(s) that are running.

  5. Click Next.

Select target(s)

  1. select Target types as EventBridge API destination.

  2. Select API destination as Use an existing API destination (Refer to 'API Destination' above).

  3. Select the Execution role as Create a new role for this specific resource.

  4. Click Next.

Configure Tags

Configure tags if required and click Next.

Review and create.

Click Review and create.

Click Create Rule.

API Destination DetailAPI Destination Detail

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

  2. API Destination details.

  3. Provide 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.

Deploy AWS CloudFormation Template

Follow the below steps to enable API-based assessment by deploying a CloudFormation template. Create stackCreate stack

  1. Log in 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.

Specify stack detailsSpecify stack details

  1. Provide the Stack name.

  2. Under Parameters, for APIGatewayURL parameter, provide the Qualys API Gateway URL. Find the Gateway URL at https://www.qualys.com/platform-identification/ 

  3. Provide the Subscription token (refer to 'Generate a subscription token' above) and click Next.

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

  5. Click Next > Submit.

Additional Information

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

Create a policy that includes the following permissions:

  • "ssm:ListInventoryEntries"

  • "ssm:DescribeInstanceInformation"

  • "ec2:DescribeInstances"

  • "ec2:DescribeAddresses"

  • "ec2:DescribeImages"

  • "ec2:DescribeRegions"

 

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

© 2024 Qualys, Inc. All rights reserved. Privacy Policy.