Protection Status Report for Acronis Cyber Cloud Protected Workloads

Managed service providers (MSPs) are busier than ever. They’re responsible for managing and protecting an ever-growing amount of data, applications, and systems for their clients in locations that span the data center to the edge and increasingly remote home offices. Historically, this level of automation and integration was not available or required complex projects, software, and custom development.

Acronis Cyber Platform API enables MSPs to seamlessly automate the deployment, management, and monitoring of backup and cyber protection operations with their full set of managed services.

Acronis Cyber Platform API helps MSPs achieve greater operational efficiency, giving more time to engage with their clients rather than focusing on deployments, service desk tickets, etc. 

Thus, the key part of integration is the monitoring capabilities. In the following tutorial let’s look, how Acronis Cyber Platform API provides enhanced capabilities to support such use cases on protection statuses reports example.

Authorization Essentials

As protection services available on a customer's level to successfully operate and retrieve reports, it needs to be authorized at the scope of a specific customer. There are many ways to achieve that: an API Client for a customer level, or a customer administrator user impersonalization, as well as re-issuing a customer-scoped protection operations-scoped token. Below, the last method is discussed. However /bc/idp/token end-point is a temporary solution before /api/2/idp/token end-point extended to support  urn:ietf:params:oauth:grant-type:jwt-bearer grant type.

To issue a base token /api/2/idp/token end-point is called using POST request with param grant_type equal client_credentials and content type application/x-www-form-urlencoded with Basic Authorization using a client_id as a user name and a client_secret as a password.

POST /api/2/idp/token HTTP/1.1
Host: dev-cloud.acronis.com
Content-Type: application/x-www-form-urlencoded
Authorization: Basic {base64_encoded_username_and_password}

grant_type=client_credentials

To issue a customer-scoped protection-scope access token /bc/idp/token end-point is called using POST request with param grant_type equal urn:ietf:params:oauth:grant-type:jwt-bearer and content type application/x-www-form-urlencoded with Bearer Authorization using a previously issued base token -- access_token and provide assertion parameter set to the access_token and scope parameter set to the urn:acronis.com:tenant-id:{customer_tenant_id} where {customer_tenant_id} is UUID of a customer to scope.

POST /bc/idp/token HTTP/1.1
Host: dev-cloud.acronis.com
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer {access_token}

grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer
&assertion={access_token}
&scope=urn%3Aacronis.com%3Atenant-id%{customer_tenant_id}

You need to securely store the received token. 
For demo purposes, we store a token as an environment variable. Please implement secure storage for your tokens.

A token has time to live and must be renewed/refreshed before the expiration time. The best practice is to check before starting any API calls sequence and renew/refresh if needed.

The scoped token has the same lifetime as the base token.  

Resources protection statuses list, filtering, and paging

To get a resource list with protection statues /api/resource_management/v4/resource_statuses end-point is called using GET request with different parameters to filter the list with Bearer Authorization using a customer-scoped protection-scope access token access_token.

This call without parameters returns a full list of resources for the current authorization scope, it supports search, filtering, and paging.

GET /api/resource_management/v4/resource_statuses HTTP/1.1
Host: dev-cloud.acronis.com
Authorization: Bearer eyJhbGciOi...t3rJZVwqJct-A

To follow the below instructions, you need to have installed Postman and Acronis Resource and Policy Management collection imported to the your localy installed Postman.

Open the Get resources protection statuses request in the Postman and then Params tab. Check that type parameter set to resource.machine to show only resources with this type.

Click Send button. You should receive a JSON response body like below.

{
    "items": [
        {
            "context": {
                "id": "aab42c95-14dc-48ab-87b4-96120111b957",
                "created_at": "2021-03-11T15:27:04.940016497Z",
                "updated_at": "2021-03-22T12:29:11.218913513Z",
                "tenant_id": "1952010",
                "external_id": "aab42c95-14dc-48ab-87b4-96120111b957@1952010",
                "type": "resource.machine",
                "agent_id": "0fe9fa94-b647-45a3-ac6f-44b617cc943a",
                "name": "stas-Virtual-Machine",
                "user_defined_name": "stas-Virtual-Machine"
            },
            "aggregate": {
                "status": "no_policies_applied"
            },
            "policies": [
                {
                    "type": "policy.backup.machine",
                    "last_run": "2021-03-11T15:32:46Z"
                }
            ]
        },
        {
            "context": {
                "id": "0817bef5-05ae-4f1f-9b31-1c092f11c12b",
                "created_at": "2021-03-22T12:22:54.118958999Z",
                "updated_at": "2021-04-13T15:05:21.053884353Z",
                "tenant_id": "1952010",
                "external_id": "0817bef5-05ae-4f1f-9b31-1c092f11c12b@1952010",
                "type": "resource.machine",
                "agent_id": "b757f01e-0b14-4788-b9a0-2671469517d7",
                "name": "test-vm-5",
                "user_defined_name": "test-vm-5"
            },
            "aggregate": {
                "status": "critical",
                "names": "New licensing protection plan;Protection Automation Training Test Plan"
            },
            "policies": [
                {
                    "type": "policy.security.antimalware_protection",
                    "next_run": "2021-03-31T14:00:00Z",
                    "last_run": "2021-03-30T18:00:02.1399766Z",
                    "last_success_run": "2021-03-25T14:00:11.4683707Z"
                },
                {
                    "type": "policy.security.patch_management",
                    "next_run": "2021-04-05T16:03:49Z"
                },
                {
                    "type": "policy.security.vulnerability_assessment",
                    "next_run": "2021-03-31T11:35:38Z",
                    "last_run": "2021-03-25T11:01:11.8704957Z",
                    "last_success_run": "2021-03-25T11:01:11.8704957Z"
                },
                {
                    "type": "policy.backup.machine",
                    "next_run": "2021-03-31T15:58:12Z",
                    "last_run": "2021-03-26T16:00:56Z",
                    "last_success_run": "2021-03-22T15:59:27Z"
                }
            ]
        }
    ]
    ...
}

Current statuses for different policies can be found in the policies object for a specific resource inside each JSON array item. The aggregate object provides aggregated status and name -- an aggregated list of protection plans. 

Enable the order parameter, check that it's set to desc(updated_at). Click Send button. You should receive a JSON response body with your resources statuses ordered from the latest updates to the oldest ones.

Change  the order parameter   to asc(updated_at). Click Send button. You should receive a JSON response body with your resources statuses ordered from oldest updates to latest ones.

Let's look into the paging. Enable the limit parameter and set it to 1. Click Send button. You should receive a JSON response body with one resource status record and cursors parameter to move to 1 next.

Enable  the after parameter and set to after fields value of cursor object. Click Send button. You should receive a JSON response body with the next resource record and cursor parameters to move to 1 next and 1 back. 

Disable the after parameter, enable before parameter, and set to before fields value of cursorobject. Click Send button. You should receive a JSON response body with the previous resource record and cursor parameters to move to 1 next. As well, these should be the resources from the previous call.

There are many parameters to filter resources statuses based on resources that belong or equal to some other entity:

• tenant_id – filter by one or more tenant ids.
• agent_id – filter by one or more agent ids.
  
• parent_id – filter by one or more resource ids, which are children for provided ones.
  
• has_member_id – filter by one or more resource ids, which are a parent for provided ones.
  
• id – filter by one or more resource ids, which expected to be included.
  
• selection_id – filter by one or more resource ids, which expected to be included.
  
• type – filter by one or more resource types.
  

Filtering by resource type is used to have in above JSONs only machines statues. These parameters can be used to limit API output depending on your development needs.

There are some request parameters to modify output:

• include_deleted – include deleted resources.
• include_attributes – include resource attributes (like the agent, OS and #CyberScore info etc.)
  
• order – enable ordering
  

The order parameter was used above. The include_attributes parameter enables enriching your JSON answer with real IP, names, OS info, etc., which is useful for reports and for matching it with your other databases.

The last but not least possibility is the possibility to search for a resource using the search query paramter.

This simple end-point provide an MSP an one-stop source of information to create statuses dashboards and enriched customers report.

Summary

Now you know how to use Acronis Account Resources Management API Postman collection to retrieve resources protection staties. You can look into the full collection of calls and try them out in Acronis Sandbox which is available after registering on Acronis Developer Portal.

Check other collections at the Postman API Network:

• Account Management API
• Task Manager, Activities and Alerts API
  
• Cyber Files API
  
• Cyber Notary API
  
• Agents API

Get started today, register on Acronis Developer Portal and see the code samples available, you can also review solutions available in the Acronis Cyber Cloud Solutions Portal.