Documentation update

   

To provide a better user experience, we have now created a separate documentation space for BMC Helix Automation Console (previously called BMC Helix Vulnerability Management).
Users of BMC Helix Automation Console can find the latest documentation at BMC Helix Automation Console. .

Using REST APIs

TrueSight Automation Consoleprovides REST API endpoints to perform all tasks currently supported by the application. These REST API endpoints are documented in the Swagger UI. 

The API follows the REST architectural style and uses resources, HTTP verbs, and status codes. JavaScript Object Notation (JSON) is used to represent data structures in request and response bodies. All endpoints (except the Login API) use the OAuth 2.0 protocol for authentication.

Accessing the Swagger host for API documentation

  1. From a supported browser, enter the following URL to access the API documentation in Swagger:


    TrueSight Automation Console: https://<FullyQualifiedDomainHostName>:<port>/apidocs/

    On the Swagger UI, you can see the APIs supported by the application. 

  2. To obtain a refresh token, based on your user profile, run the following API:

    API calls based on the user


    API for a Server Automation user: /api/v3/users/tssa/login

  3. Provide the following credentials and click Execute:
    1. Username to log in to Automation Console
    2. Password

    A refresh token is generated, which is valid for 24 hours only.

  4. To obtain an access token to try the APIs, run the /api/v3/auth/tokens API call by using the refresh token.
  5. Copy the token returned by the API call.

    An access token is valid for 15 minutes only.

    Note

    If you intend to use a REST API client, such as Postman, you must pass the authorization token in the request header for any REST API call.

  6. On the Login and Administration Service APIs page, click Authorize and provide the token in the authorizations window.

You can now access, try out, and execute any API calls using the Swagger UI. 

Login and Administration Service APIs

Contains APIs that support functions related to session management, Service Level Agreements, security groups, and BMC Remedy Single Sign-On. 

API callDescription
Login API

POST/api/v3/users/tssa/login

Generates a refresh token to log on to TrueSight Server Automation.

POST/api/v3/auth/tokens

Generates an access token using the refresh token.
SLA API

GET/api/v1/config/slas

Retrieves the service level agreements defined in the Automation Console.

PUT/api/v1/config/slas

Updates the deadline and warning threshold for SLA severity levels.
Security Groups API

POST/api/v1/config/securitygroups

Creates a new security group.

GET/api/v1/config/securitygroups

Retrieves a list of security groups with details such as the group ID, role, name, description, creation date, and default job path, default depot path, and site details.

GET/api/v1/config/securitygroups/{id}

Retrieves details about a security group as per the specified group ID.

PUT/api/v1/config/securitygroups/{id}

Updates a specified security group by using the group ID.

GET/api/v1/config/tssa/roles

Retrieves all roles created in TrueSight Server Automation.

GET/api/v1/config/tssa/groups/{type}

Retrieves security group profile by group type.
BMC Remedy Single Sign-On API

POST/api/v1/config/rsso

Configures BMC Remedy Single Sign-On.

Note

You must have administrator permissions to use this API call.

Support API

DELETE/api/v1/config/securitygroups/{id}

Deletes the specified security group.

Note

BMC recommends that you do not use this API call. This API call is only made available to the BMC Customer Support team for debugging or recovering from problems.

Connectors Service APIs

Contains API calls for working with all the connectors in Automation Console. 

API callDescription
Connectors API
POST/api/v1/connectordefinitions/search
Searches for a connector definition, which includes information about the connector name, type, and so on.

GET/api/v1/connectors/{id}/getConfigurations

Retrieves configurations for a connector instance.

POST/api/v1/connectors/{id}/updateConfigurations

Updates a connector configuration.

POST/api/v1/connectors/search

Searches for a connector.

POST/api/v1/connectorservice/connectors/{ConnectorId}/activate

Activates a connector.

POST/api/v1/connectorservice/connectors/{ConnectorId}/deactivate

Deactivates a connector.

Exceptions Service APIs

Contains APIs for creating, updating, deleting, and searching exceptions in the Automation Console.

API call

Description

POST/api/v1/exceptions

Creates one or more exceptions.

PATCH/api/v1/exceptions/{exceptionId}/status

Updates the status of an exception. (Enable or Disable)

DELETE/api/v1/exceptions/{exceptionId}

Deletes an exception.

PATCH/api/v1/exceptions/{exceptionId}

Updates the end date of an exception.

POST/api/v1/exceptions/search

Searches for an exception.
Support API

POST/api/v1/exceptions/sync

Exceptions that are in an enabled or active state move to an Active or Expired state based on their scheduled date, which runs at 12:00 AM UTC. If the scheduler does not work as expected, this API call forcefully executes active or enabled exceptions.

Note

BMC recommends that you do not use this API call. This API call is only made available to the BMC Customer Support team for debugging or recovering from problems.

Patch Catalog Service APIs

Contains APIs for working with catalogs and patches in Automation Console. 

API call

Description
Catalogs API

GET/api/v2/catalogs

Retrieves all catalogs imported inAutomation Console.

POST/api/v2/catalogs


Imports a new catalog from Server Automation.

GET/api/v1/catalogs/tssa

Retrieves all Microsoft Windows, Red Hat Linux, SUSE Linux, OEL, and CentOS catalogs available in Server Automation.

GET/api/v1/catalogs/tssa/{catalogId}

Retrieves details for a catalog created in Server Automation for a specified catalog ID.

GET/api/v2/catalogs/{catalogId}

Retrieves details for a catalog imported in  Automation Console for a specified catalog ID.

PUT/api/v2/catalogs/{catalogId}



Updates schedule for a specified catalog ID.

DELETE/api/v2/catalogs/{catalogId}

Deletes the specified catalog from Automation Console.

PUT/api/v2/catalogs/{catalogId}/enable

Enables automatic synchronization for a catalog.

PUT/api/v2/catalogs/{catalogId}/disable

Disables automatic synchronization for a catalog.
Patches API

PUT/api/v1/catalogs/patch

Retrieves all patches based on the patch IDs.

PUT/api/v1/catalogs/{catalogId}/patch/search

Retrieves all patches of the specified catalog (that match the filters) from Automation Console

PUT/api/v1/catalogs/patch/search

Retrieves patches based on the specified CVE IDs.

PUT/api/v2/catalogs/patch/search

Retrieves patches based on CVE IDs.

Support API

POST/api/v2/catalogs/{catalogId}/sync

Performs a force sync of the catalog details from TrueSight Server Automation.

Note

BMC recommends that you do not use this API call. This API call is only made available to the BMC Customer Support team for debugging or recovering from problems.

Patch Policy and Operations APIs

Contains the APIs for working with remediation jobs, patch policies, compliance scan policies, vulnerability scans, and so on. 

API call

Description
JobRun API

GET/api/v1/policies/job/{jobRunId}/summary



Retrieves summary for the specified job run ID.

GET/api/v1/policies/job/{jobRunId}/target

Retrieves summary for the specified job run ID and target.

GET/api/v1/policies/job/{jobRunId}/target/{targetId}

Retrieves summary for the specified job run ID and target ID.

GET/api/v1/policies/policy/{policyId}/jobRuns

Retrieves job runs for the specified policy ID.

GET/api/v1/policies/{policyId}/runs/{runId}/logs

Retrieves event logs for a specified policy scan run.

NEW IN 21.02.01GET/api/v2/policies/operations/{operation_id}/jobs/{job_id}/runs/{job_run_id}/summary

Retrieves the job run summary for the specified operation ID, job ID, job run ID, and sequence ID.

NEW IN 21.02.01GET

/api/v2/policies/operations/{operation_id}/jobs/{job_id}/runs/{job_run_id}/target


Retrieves target wise job runs from TrueSight Server Automation for the specified operation ID, job ID, job run ID, and sequence ID.

NEW IN 21.02.01GET/api/v2/policies/operations/{operation_id}/jobs/{job_id}/runs

Retrieves all the job runs for the specified policy ID, job ID, and sequence ID.
Patch Policy APIDescription

POST/api/v1/policies

Creates a new patch policy.

GET/api/v1/policies/tssa/groups/{type}

Retrieves all static groups created in Server Automation.

POST/api/v1/policies/tssa/groups/{type}

Creates a static group in Server Automation.

GET/api/v1/policies/tssa/smart-groups/{type}

Retrieves all dynamic groups created in Server Automation.

POST/api/v1/policies/policy/{policyId}/jobruns

Executes a patch policy associated with specified policy ID immediately.

GET/api/v1/policies/search

Retrieves a list of policies created in the Automation Console.

GET/api/v2/policies

Retrieves a list of policies created in the Automation Console.

PATCH/api/v2/policies/{policyId}/bookmark

Bookmarks an existing policy.

This API call is applicable for operation templates only.

POST/api/v1/policies/reports/patch-compliance

Retrieves patch compliance results for a policy.

POST/api/v1/policies/reports/patch-compliance/detail

Retrieves patch compliance details for a policy.

GET/api/v1/policies/{policy_id}

Retrieves information for a specified policy ID.

PUT/api/v1/policies/{policy_id}

Updates an existing policy.
Vulnerability scan API

POST/api/v1/policies/import-scan

Imports a vulnerability scan.

TrueSight Server Automation API

GET/api/v1/policies/tssa/nshscripts


Retrieves all NSH Scripts defined in Server Automation.

GET/api/v1/policies/tssa/bl-packages

Retrieves all BLPackages defined in Server Automation.

GET/api/v1/policies/tssa/nshscripts/{scriptId}

Retrieves NSH Script details from Server Automation.

POST/api/v1/policies/tssa/depots/search



Search depot object based on given condition.

GET/api/v1/policies/tssa/jobs/{type}

Retrieves all the jobs defined in Server Automation.

GET/api/v1/policies/tssa/jobs/{type}/{jobId}

Retrieves information for a specified job ID from Server Automation.

Operations API

POST/api/v1/policies/operations

Creates a remediation operation in Automation Console.

POST/api/v1/policies/operations/search

Retrieves all operations in Automation Console.

POST/api/v1/policies/operations/prepare-list

Prepares an operation list.

PATCH/api/v1/policies/operations/execute/{operationId}


Executes an operation for a specified ID.

GET/api/v1/policies/operations/{operationId}/suboperations

Retrieves child operations of a parent operation.

DELETE/api/v1/policies/operations/{operation_id}

Deletes a specified operation.

NEW IN 21.02.01GET

/api/v2/policies/operations/{operation_id}/jobs

Retrieves the jobs of the specified Batch job operation.
Operation Template API

POST/api/v2/policies/operation-templates

Creates an operation template in Automation Console.

POST/api/v2/policies/operation-templates/search

Retrieves an operation template based on the specified search filters.

GET/api/v2/policies/operation-templates/{operation_template_id}

Retrieves an operation template.

DELETE/api/v2/policies/operation-templates/{operation_template_id}

Deletes an operation template.

PATCH/api/v2/policies/operation-templates/{operation_template_id}

Shares an operation template with the specified security groups.

PUT/api/v2/policies/operation-templates/{operation_template_id}

Updates an operation template.
Compliance Policy API

POST/api/v2/policies/compliance-scans

Creates a new compliance policy.

PUT/api/v2/policies/compliance-scans/{policyId}/enable

Enables a compliance scan policy.

PUT/api/v2/policies/compliance-scans/{policyId}/disable

Disables a compliance scan policy.

DELETE/api/v2/policies/compliance-scans/{policyId}

Deletes a compliance scan policy.

POST/api/v2/policies/compliance-scans/{policyId}/jobruns

Executes the compliance scan policy associated with specified policy ID immediately.
Compliance Job Run API

GET/api/v2/policies/compliance-scans/{complianceScanPolicyId}/runs

Retrieves job runs for the specified compliance scan policy ID.

GET/api/v2/policies/compliance-scans/runs/{runId}/summary

Retrieves an overall summary for the specified compliance scan policy ID and job run ID.

GET/api/v2/policies/compliance-scans/runs/{runId}/targets

Retrieves a summary of the job runs for the specified compliance scan policy ID and job run ID.

GET/api/v2/policies/compliance-scans/runs/{runId}/targets/{targetId}

Retrieves job runs target details for the specified compliance scan policy ID, job run ID, and target ID
ITIL API

GET/api/v1/policies/itil/configurations

Retrieves IT Service Management configuration.

GET/api/v1/policies/itil/status/{changeId}

Retrieves the status of the change request created in the ITSM system.
Status Count

GET/api/v1/policies/operations/status/summary

Retrieves operations count by status.
Patch Policy API

POST/api/v2/policies/patch-policies

Creates a new patch policy.

GET/api/v2/policies/patch-policies

Retrieves all patch policies.

GET/api/v2/policies/patch-policies/{policy_id}

Retrieves information for a specified patch policy ID.

PUT/api/v2/policies/patch-policies/{policy_id}


Updates an existing patch policy.

DELETE/api/v2/policies/patch-policies/{policy_id}

Deletes a patch policy.

PUT/api/v2/policies/patch-policies/{policy_id}/enable

Enables the patch policy for a specified policy ID.

PUT/api/v2/policies/patch-policies/{policy_id}/disable

Disables the patch policy for a specified policy ID.

POST/api/v2/policies/patch-policies/{policyId}/jobruns

Immediately executes the scan policy associated with the specified patch policy ID.

GET/api/v2/policies/patch-policies/summary

Retrieves a count of policies group by operating system and its vendor.
Templates API

GET/api/v2/policies/tssa/templates

Retrieves all TrueSight Server Automation compliance templates.

Violations and Dashboard Service APIs

Contains APIs for the Dashboard, Missing Patches (referred as Violations in the API), Activities, Custom tags, and  Assets.

API call

Description
Activities API

GET/api/v1/activities/{id}

Retrieves the details for an activity such as the status.

PUT/api/v1/activities/cancel

Cancels an activity and marks it as Failed.
Assets

POST/api/v1/violations/reports/targets/{type}

Retrieves all assets based on the asset type.

PUT/api/v1/violations/asset/manual-map/{resourceId}

Maps scanner asset to endpoint targets manually.

PUT/api/v1/violations/asset/unmap

Unmaps scanned assets with the endpoints in the endpoint manager.

GET/api/v1/assets/metadata/business-services

Retrieves a list of unique business services.

GET/api/v1/assets/metadata/os/{type}

Retrieves a list of unique operating systems and vendors.

POST/api/v1/violations/assets

Retrieves details of all the assets for a specified given patch policy.
Custom Tags

POST/api/v1/violations/tags/search

Retrieves unique custom tags.

POST/api/v1/violations/tags

Creates custom tags.

Note

You must have administrator permissions to use this API call.

GET/api/v1/violations/tags

Retrieves all custom tags.

PUT/api/v1/violations/tags/{id}

Updates the custom tag for the specified tag ID.

Note

You must have administrator permissions to use this API call.

DELETE/api/v1/violations/tags/{id}

Deletes the custom tag for a specified ID.
Dashboard API

POST/api/v1/violations/reports/targets/severity/summary

Generates data for the Impacted Assets by Severity widget on the dashboard.

POST/api/v1/violations/reports/targets/severity/detail

Generates asset details by severity levels.

POST/api/v1/violations/reports/targets/patch-compliance/summary

Generates data for the Patch Compliance widget on the dashboard.

POST/api/v1/violations/reports/targets/patch-compliance/detail

Generates patch compliance details such as the number of installed and missing patches on assets according to the policy on the dashboard.

POST/api/v1/violations/reports/{type}/summary

Generates data for the Impacted Assets by SLA and Unique Missing Patches by Age widgets on the dashboard.

POST/api/v1/violations/reports/sla/detail

Generates details for the assets and missing patches based on their SLA levels.

POST/api/v1/violations/reports/trends/weeks

Generates data for the Remediation Trend graph on the dashboard.

POST/api/v1/violations/reports/trends/weeks/detail

Generates details such as the missing and remediated patches in the Remediation Trend graph.

POST/api/v1/violations/reports/states/average-days/weeks

Gets the average time for a state change in the current week.

POST/api/v1/violations/reports/rank/violations

Generates data for the Top 10 Missing Patches widget.

POST/api/v1/violations/reports/states/summary

Generates data for the violations based on stage.

POST/api/v1/violations/reports/rank/violations/detail

Generates asset details for the Top 10 Missing Patches widget.

POST/api/v1/violations/reports/violations/severity/summary

Fetches violations count by severity.

POST/api/v1/violations/reports/violations/sla/summary

Fetches violations count by SLA.

POST/api/v1/violations/reports/services/summary

Retrieves the list of objects with details such as business service name, violation and assets count associated with that particular business service.

GET/api/v1/violations/reports/targets/discovery/mapped/{sourcetype}

Retrieves the count of targets mapped to discovery based on selected source.

POST/api/v1/violations/reports/services/summary/{types}

Retrieves the list of object having violation name and severity or asset name and operating system platform based on the request type.

POST/api/v1/violations/reports/rank/owner

Fetches data for the Top 10 Missing Patches by Owner widget.

POST/api/v1/violations/reports/rank/owner/details/{type}

Fetches asset details for the Top 10 Missing Patches by Owner widget.

POST
/api/v2/violations/reports/patch-compliance/summary

Retrieves the list of objects with the operating system and its missing count.

POST/api/v2/violations/reports/policies/summary

Retrieves the list of objects with policy ID and rules and assets associated with that policy ID along with state wise distribution of vulnerability and assets.

POST/api/v2/violations/reports/policies/details/{policy_id}

Retrieves the details for the given policy ID along with rules and assets associated with that policy id along with state wise distribution of vulnerability and assets.

POST/api/v2/violations/reports/policies/violations/summary

Retrieves the list of objects with details such as the violation name, assets count, policy details and SLA type.

POST/api/v2/violations/reports/states/summary

Retrieves the summary for different compliance states for vulnerability and assets.
Violations API

POST/api/v1/violations

Creates violations for a specified asset.

GET/api/v1/violations

Retrieves details of the violations.

PATCH/api/v1/violations

Updates violation fields like risk score, SLA, risk owner, and risk tags based on the given filter criteria.

POST/api/v1/violations/upload-tags

Imports tags in a CSV file. Tags such as the risk score, owner, SLA deadlines and warnings can be updated.

GET/api/v1/violations/{id}

Retrieves details of the violations based on the ID.

POST/api/v2/violations/search/{type}

Retrieves all vulnerabilities or missing patches.

POST/api/v1/violations/reports/patch

Exports the patch report in .csv format.

GET/api/v1/violations/metadata/cveid

Retrieves all distinct CVE IDs identified against the violations.

POST/api/v1/violations/riskscore

Retrieves all risk scores.

POST/api/v1/violations/owner

Gets all risk owners.
Vulnerability API

POST/api/v1/violations/reports/vulnerability

Exports the vulnerability report in .csv format.

POST/api/v2/violations/search/{type}

Retrieves all vulnerabilities or missing patches

POST/api/v1/violations/search/vulnerabilities

Retrieves all vulnerabilities.

POST/api/v1/violations/search/vats

Retrieves all actionable VATs.

POST/api/v2/violations/search/vats

Retrieves all actionable VATs.

PUT/api/v1/violations/manual-map/{id}

Maps remediation content to the given vulnerability manually.

DELETE/api/v1/violations/unmap/{id}

Removes mapped remediation contents for the vulnerability.

POST/api/v1/violations/auto-map

Maps vulnerabilities with remediation content for all the given CVE IDs.
Tagging API

POST/api/v1/assets/scanned/tags

Imports tags in a CSV file.

Support API

Note

BMC recommends that you do not use these API calls. These APIs are only made available to the BMC Customer Support team for debugging or recovering from problems.

GET/api/v1/activities/{id}

Retrieves details of an activity.

PUT/api/v1/activities/cancel

Cancels an activity and marks it as FAILED.

POST/api/v1/violations/poolsync

Retrieves all the resources from the resource service and sync it to asset state service database.



Was this page helpful? Yes No Submitting... Thank you

Comments