IBM API Samples for QRadar

This directory contains Python scripts demonstrating how to interact with the /config/domain_management/domains endpoints of the API. These samples cover common operations including retrieving domain information, deleting domains, and modifying domain configurations.

Important Safety Note: These samples are provided for reference. It is strongly advised not to run these scripts against production systems. Some scripts (like 02_DeleteDomain.py and 03_ModifyDomain.py) are designed to temporarily change the state of the domain configuration.

The custom_properties directory provides Python sample scripts for interacting with custom property endpoints. These samples cover two main categories of properties: Event Properties and Flow Properties, each supporting two types of definitions: Regex Properties and Property Expressions.

To find the full list of available endpoints and their parameters, you can use the following resources:

• Interactive Help Page: https://<hostname>/api_doc
• API Discovery Endpoints: /api/help/versions and /api/help/resources

The Ariel API (/ariel endpoints) allows you to interact with QRadar data using the Ariel V3 query language (AQL).

To discover available endpoints and their parameters, you can:

1. Access the REST API interactive help page at https://<hostname>/api_doc.
2. Retrieve a list of available endpoints via the API at the /api/help/endpoints endpoint.

Warning: It is strongly advised not to run these samples against production systems.

The tenant/ directory contains introductory Python scripts designed to teach the basics of API interaction, including authentication, parameter passing, and error handling.

Available samples:

• 01_GetTenant.py: Demonstrates how to retrieve a list of tenants and how to send simple requests to REST API endpoints.
• 02_CreateUpdateDeleteTenant.py: Demonstrates how to perform CRUD (Create, Read, Update, Delete) operations on a tenant.

The Custom Actions API allows you to manage custom action interpreters, scripts, and actions via the /analytics/custom_actions endpoints.

Important Requirements:

• Permissions: Access to these endpoints is restricted to admin users.
• Deployment: Custom action scripts must be deployed from the admin tab before they can be executed.
• Documentation: You can find the full list of endpoints and parameters at the interactive help page: https://<hostname>/api_doc. Alternatively, you can retrieve available endpoints via the /api/help/versions endpoint.

The sample package provides examples for several API categories, but does not cover all available endpoints.

Available Sample Categories

• Introduction: Low-level API usage.
• Reference Data: Endpoints in /reference_data.
• Ariel: Endpoints in /ariel.
• Offense: Endpoints in /siem/offenses.
• Domain Management: Endpoints in /config/domain_management/domains.
• Custom Actions: Endpoints in /analytics/custom_actions.
• API CLI: A command-line client for accessing the API.

Finding API Documentation

• Interactive Help: View the REST API interactive help page on your QRadar installation at https://<hostname>/api_doc.
• Endpoint List: Retrieve a list of available endpoints directly from the API at the /help/endpoints endpoint.

Several shared parameters can be used across many endpoints (such as reference_data/sets) to control the shape and size of the response:

• filter (query parameter): Restricts the elements returned in a list based on the contents of the fields being returned.
• Range (header parameter): Used for paging elements of a list by specifying the start and end values of the desired range.
• fields (query parameter): Specifies exactly which fields in the return object you are interested in. Only the requested fields will be returned in the response.

The siem/offenses endpoint supports several parameters to refine data retrieval:

• fields: Use this parameter to filter which specific fields are returned in the response, making the data more concise.
• filter: Use this parameter to filter the actual records returned (e.g., filtering by status such as OPEN or HIDDEN).
• Range (Header): Use the Range HTTP header to implement pagination when retrieving large sets of offense data.

Common workflows include:

• Retrieving all offenses.
• Retrieving only OPEN offenses using a filter.
• Retrieving only HIDDEN offenses using a filter.
• Paging through results to manage large datasets.

When interacting with the API, you may encounter several types of responses related to errors or lifecycle changes:

• Error Responses: The API returns specific information in error responses to help diagnose common mistakes (see 05_Errors.py).
• Deprecated API Endpoints: If you call a deprecated endpoint, the API returns a Deprecated response header.
• Removed API Endpoints: If you call an endpoint that has been removed, the API returns a Removed response message.

You can modify the lifecycle of an offense (such as hiding, showing, or closing it) using POST requests to the appropriate endpoints.

Key Operations:

• Hide/Show Offense: Change the status of an offense using the status field via a POST endpoint.
• Closing an Offense: To properly close an offense in a manner consistent with QRadar, follow these steps:
  1. Select an offense.
  2. Select a valid closing reason (retrievable via the API).
  3. Modify the status field to CLOSED.
  4. Post a note to the offense.
• Notes: You can retrieve existing notes for an offense or create new notes using the siem API.

The sample 04_postCustomActions.py demonstrates how to add or modify components.

WARNING: This sample makes changes to the system. Do not run this against a production system.

Capabilities demonstrated:

• Posting new custom action scripts to the system.
• Updating existing scripts on the system.
• Posting new custom actions to the system.
• Updating existing custom actions on the system.