Zero Trust Assessment

The Zero Trust Assessment service collection provides operations for retrieving Zero Trust Assessment data across your environment. Query assessment scores by host, retrieve audit reports, search assessments by score ranges, and perform combined queries with FQL filtering and pagination.

Language	Last Update
Python	v1.6.5
PowerShell	v2.2.9
Go	v0.22.0
TypeScript	v0.6.0
Rust	v0.7.1
Ruby	v1.4.0

---

---

Table of Contents

Operation	Description
getAssessmentsByScoreV1 get_assessments_by_score	Get Zero Trust Assessment data for one or more hosts by providing a customer ID (CID) and a range of scores.
getAssessmentV1 get_assessment	Get Zero Trust Assessment data for one or more hosts by providing agent IDs (AID) and a customer ID (CID).
getAuditV1 get_audit	Get the Zero Trust Assessment audit report for one customer ID (CID).

---

getAssessmentsByScoreV1

Get Zero Trust Assessment data for one or more hosts by providing a customer ID (CID) and a range of scores.

Method GET

Route /zero-trust-assessment/queries/assessments/v1

Scope Zero Trust Assessment: READ

PEP 8 get_assessments_by_score

Parameters

filter query · string

FQL formatted string containing the filter to use to limit results.

limit query · integer

The number of scores to return in this response (min: 1, max: 1000, default: 100). Use with the after parameter to manage pagination of results.

after query · string

A pagination token used with the limit parameter to manage pagination of results. On your first request, don’t provide an after token. On subsequent requests, provide the after token from the previous response to continue from that place in the results.

sort query · string

Sort accounts by their properties. A single sort field is allowed. Defaults to ascending. Supported sort option include:

Available values (1)

score

parameters query · dictionary

Full query string parameters payload in JSON format. Not required when using other keywords.

Code Examples

Python

PEP 8

from falconpy import ZeroTrustAssessment

falcon = ZeroTrustAssessment(client_id=CLIENT_ID,
                             client_secret=CLIENT_SECRET
                             )

response = falcon.get_assessments_by_score(after="string",
                                           filter="string",
                                           limit=integer)
print(response)

Operation ID

from falconpy import ZeroTrustAssessment

falcon = ZeroTrustAssessment(client_id=CLIENT_ID,
                             client_secret=CLIENT_SECRET
                             )

response = falcon.getAssessmentsByScoreV1(after="string",
                                          filter="string",
                                          limit=integer)
print(response)

Uber

from falconpy import APIHarnessV2

falcon = APIHarnessV2(client_id=CLIENT_ID,
                      client_secret=CLIENT_SECRET
                      )

response = falcon.command("getAssessmentsByScoreV1",
                          filter="string",
                          limit=integer,
                          after="string",
                          sort="string")
print(response)

PowerShell

Get-FalconZta -Filter "string" `
  -Sort "string" `
  -Limit integer

Go

package main

import (
  "context"
  "fmt"
  "os"

  "github.com/crowdstrike/gofalcon/falcon"
  "github.com/crowdstrike/gofalcon/falcon/client/zero_trust_assessment"
)

func main() {
  client, err := falcon.NewClient(&falcon.ApiConfig{
    ClientId:     os.Getenv("FALCON_CLIENT_ID"),
    ClientSecret: os.Getenv("FALCON_CLIENT_SECRET"),
    Context:      context.Background(),
  })
  if err != nil {
    panic(err)
  }

  limit := int64(0)
  after := "string"
  sort := "string"

  response, err := client.ZeroTrustAssessment.GetAssessmentsByScoreV1(
    &zero_trust_assessment.GetAssessmentsByScoreV1Params{
      Filter: "string",
      Limit: &limit,
      After: &after,
      Sort: &sort,
      Context: context.Background(),
    },
  )
  if err != nil {
    panic(falcon.ErrorExplain(err))
  }

  fmt.Printf("%+v\n", response.Payload)
}

TypeScript

import { FalconClient } from "crowdstrike-falcon";

const client = new FalconClient({
  cloud: process.env.FALCON_CLOUD!,
  clientId: process.env.FALCON_CLIENT_ID!,
  clientSecret: process.env.FALCON_CLIENT_SECRET!,
});

const response = await client.zeroTrustAssessment.getAssessmentsByScoreV1(
  "string",  // filter
  integer,  // limit
  "string",  // after
  "string"  // sort
);

console.log(response);

Rust

use rusty_falcon::apis::zero_trust_assessment_api::get_assessments_by_score_v1;
use rusty_falcon::easy::client::FalconHandle;

#[tokio::main]
async fn main() {
    let falcon = FalconHandle::from_env().await.expect("Could not authenticate");

    let response = get_assessments_by_score_v1(
        &falcon.cfg,  // configuration
        "string",  // filter
        Some(integer),  // limit
        Some("string"),  // after
        Some("string"),  // sort
    ).await.expect("API call failed");

    println!("{:?}", response);
}

Ruby

require "crimson-falcon"

Falcon.configure do |config|
  config.client_id = ENV["FALCON_CLIENT_ID"]
  config.client_secret = ENV["FALCON_CLIENT_SECRET"]
  config.cloud = ENV["FALCON_CLOUD"]
end

api = Falcon::ZeroTrustAssessment.new

response = api.get_assessments_by_score_v1('string')

puts response

Responses

200 OK

[
  {
    "aid": "string",
    "score": 0
  }
]

400 Number of agent IDs exceeds the limit of 1000.

{
  "errors": [
    {
      "code": 0,
      "id": "string",
      "message": "string"
    }
  ],
  "meta": {
    "pagination": {
      "limit": 0,
      "next": "string",
      "offset": "string",
      "total": 0
    },
    "powered_by": "string",
    "query_time": 0.0,
    "trace_id": "string"
  },
  "resources": [
    {
      "aid": "string",
      "score": 0
    }
  ]
}

403 Forbidden

{
  "errors": [
    {
      "code": 0,
      "id": "string",
      "message": "string"
    }
  ],
  "meta": {
    "pagination": {
      "limit": 0,
      "offset": 0,
      "total": 0
    },
    "powered_by": "string",
    "query_time": 0.0,
    "trace_id": "string",
    "writes": {
      "resources_affected": 0
    }
  }
}

404 One or more of the specified agent IDs is not found.

{
  "errors": [
    {
      "code": 0,
      "id": "string",
      "message": "string"
    }
  ],
  "meta": {
    "pagination": {
      "limit": 0,
      "next": "string",
      "offset": "string",
      "total": 0
    },
    "powered_by": "string",
    "query_time": 0.0,
    "trace_id": "string"
  },
  "resources": [
    {
      "aid": "string",
      "score": 0
    }
  ]
}

429 Too Many Requests

{
  "errors": [
    {
      "code": 0,
      "id": "string",
      "message": "string"
    }
  ],
  "meta": {
    "pagination": {
      "limit": 0,
      "offset": 0,
      "total": 0
    },
    "powered_by": "string",
    "query_time": 0.0,
    "trace_id": "string",
    "writes": {
      "resources_affected": 0
    }
  }
}

500 Unexpected Error

{
  "errors": [
    {
      "code": 0,
      "id": "string",
      "message": "string"
    }
  ],
  "meta": {
    "pagination": {
      "limit": 0,
      "offset": 0,
      "total": 0
    },
    "powered_by": "string",
    "query_time": 0.0,
    "trace_id": "string",
    "writes": {
      "resources_affected": 0
    }
  }
}

---

---

getAssessmentV1

Get Zero Trust Assessment data for one or more hosts by providing agent IDs (AID) and a customer ID (CID).

Method GET

Route /zero-trust-assessment/entities/assessments/v1

Scope Zero Trust Assessment: READ

PEP 8 get_assessment

Parameters

ids query · string or list of strings

One or more agent IDs, which you can find in the data.zta file, or the Falcon console.

parameters query · dictionary

Full query string parameters payload in JSON format. Not required when using other keywords.

Code Examples

Python

PEP 8

from falconpy import ZeroTrustAssessment

falcon = ZeroTrustAssessment(client_id=CLIENT_ID,
                             client_secret=CLIENT_SECRET
                             )

id_list = 'ID1,ID2,ID3'  # Can also pass a list here: ['ID1', 'ID2', 'ID3']

response = falcon.get_assessment(ids=id_list)
print(response)

Operation ID

from falconpy import ZeroTrustAssessment

falcon = ZeroTrustAssessment(client_id=CLIENT_ID,
                             client_secret=CLIENT_SECRET
                             )

id_list = 'ID1,ID2,ID3'  # Can also pass a list here: ['ID1', 'ID2', 'ID3']

response = falcon.getAssessmentV1(ids=id_list)
print(response)

Uber

from falconpy import APIHarnessV2

falcon = APIHarnessV2(client_id=CLIENT_ID,
                      client_secret=CLIENT_SECRET
                      )

id_list = 'ID1,ID2,ID3'  # Can also pass a list here: ['ID1', 'ID2', 'ID3']

response = falcon.command("getAssessmentV1",
                          ids=id_list)
print(response)

PowerShell

Get-FalconZta -Id @("ID1", "ID2")

Go

package main

import (
  "context"
  "fmt"
  "os"

  "github.com/crowdstrike/gofalcon/falcon"
  "github.com/crowdstrike/gofalcon/falcon/client/zero_trust_assessment"
)

func main() {
  client, err := falcon.NewClient(&falcon.ApiConfig{
    ClientId:     os.Getenv("FALCON_CLIENT_ID"),
    ClientSecret: os.Getenv("FALCON_CLIENT_SECRET"),
    Context:      context.Background(),
  })
  if err != nil {
    panic(err)
  }

  response, err := client.ZeroTrustAssessment.GetAssessmentV1(
    &zero_trust_assessment.GetAssessmentV1Params{
      Ids: []string{"ID1", "ID2", "ID3"},
      Context: context.Background(),
    },
  )
  if err != nil {
    panic(falcon.ErrorExplain(err))
  }

  fmt.Printf("%+v\n", response.Payload)
}

TypeScript

import { FalconClient } from "crowdstrike-falcon";

const client = new FalconClient({
  cloud: process.env.FALCON_CLOUD!,
  clientId: process.env.FALCON_CLIENT_ID!,
  clientSecret: process.env.FALCON_CLIENT_SECRET!,
});

const response = await client.zeroTrustAssessment.getAssessmentV1(["ID1", "ID2", "ID3"]);  // ids

console.log(response);

Rust

use rusty_falcon::apis::zero_trust_assessment_api::get_assessment_v1;
use rusty_falcon::easy::client::FalconHandle;

#[tokio::main]
async fn main() {
    let falcon = FalconHandle::from_env().await.expect("Could not authenticate");

    let response = get_assessment_v1(
        &falcon.cfg,  // configuration
        vec!["string".to_string()],  // ids
    ).await.expect("API call failed");

    println!("{:?}", response);
}

Ruby

require "crimson-falcon"

Falcon.configure do |config|
  config.client_id = ENV["FALCON_CLIENT_ID"]
  config.client_secret = ENV["FALCON_CLIENT_SECRET"]
  config.cloud = ENV["FALCON_CLOUD"]
end

api = Falcon::ZeroTrustAssessment.new

response = api.get_assessment_v1(['ID1', 'ID2', 'ID3'])

puts response

Responses

200 OK

[
  {
    "aid": "string",
    "assessment": {},
    "assessment_items": {},
    "cid": "string",
    "event_platform": "string",
    "modified_time": "string",
    "product_type_desc": "string",
    "sensor_file_status": "string",
    "system_serial_number": "string"
  }
]

400 Number of agent IDs exceeds the limit of 1000.

{
  "errors": [
    {
      "code": 0,
      "id": "string",
      "message": "string"
    }
  ],
  "meta": {
    "pagination": {
      "limit": 0,
      "offset": 0,
      "total": 0
    },
    "powered_by": "string",
    "query_time": 0.0,
    "quota": {
      "total": 0,
      "used": 0
    },
    "trace_id": "string",
    "writes": {
      "resources_affected": 0
    }
  },
  "resources": [
    {
      "aid": "string",
      "assessment": {},
      "assessment_items": {},
      "cid": "string",
      "event_platform": "string",
      "modified_time": "string",
      "product_type_desc": "string",
      "sensor_file_status": "string",
      "system_serial_number": "string"
    }
  ]
}

403 Forbidden

{
  "errors": [
    {
      "code": 0,
      "id": "string",
      "message": "string"
    }
  ],
  "meta": {
    "pagination": {
      "limit": 0,
      "offset": 0,
      "total": 0
    },
    "powered_by": "string",
    "query_time": 0.0,
    "trace_id": "string",
    "writes": {
      "resources_affected": 0
    }
  }
}

429 Too Many Requests

{
  "errors": [
    {
      "code": 0,
      "id": "string",
      "message": "string"
    }
  ],
  "meta": {
    "pagination": {
      "limit": 0,
      "offset": 0,
      "total": 0
    },
    "powered_by": "string",
    "query_time": 0.0,
    "trace_id": "string",
    "writes": {
      "resources_affected": 0
    }
  }
}

500 Unexpected Error

{
  "errors": [
    {
      "code": 0,
      "id": "string",
      "message": "string"
    }
  ],
  "meta": {
    "pagination": {
      "limit": 0,
      "offset": 0,
      "total": 0
    },
    "powered_by": "string",
    "query_time": 0.0,
    "trace_id": "string",
    "writes": {
      "resources_affected": 0
    }
  }
}

---

---

getAuditV1

Get the Zero Trust Assessment audit report for one customer ID (CID).

Method GET

Route /zero-trust-assessment/entities/audit/v1

Scope Zero Trust Assessment: READ

PEP 8 get_audit

Code Examples

Python

PEP 8

from falconpy import ZeroTrustAssessment

falcon = ZeroTrustAssessment(client_id=CLIENT_ID,
                             client_secret=CLIENT_SECRET
                             )

response = falcon.get_audit()
print(response)

Operation ID

from falconpy import ZeroTrustAssessment

falcon = ZeroTrustAssessment(client_id=CLIENT_ID,
                             client_secret=CLIENT_SECRET
                             )

response = falcon.getAuditV1()
print(response)

Uber

from falconpy import APIHarnessV2

falcon = APIHarnessV2(client_id=CLIENT_ID,
                      client_secret=CLIENT_SECRET
                      )

response = falcon.command("getAuditV1")
print(response)

PowerShell

Get-FalconZta

Go

package main

import (
  "context"
  "fmt"
  "os"

  "github.com/crowdstrike/gofalcon/falcon"
  "github.com/crowdstrike/gofalcon/falcon/client/zero_trust_assessment"
)

func main() {
  client, err := falcon.NewClient(&falcon.ApiConfig{
    ClientId:     os.Getenv("FALCON_CLIENT_ID"),
    ClientSecret: os.Getenv("FALCON_CLIENT_SECRET"),
    Context:      context.Background(),
  })
  if err != nil {
    panic(err)
  }

  response, err := client.ZeroTrustAssessment.GetAuditV1(
    &zero_trust_assessment.GetAuditV1Params{
      Context: context.Background(),
    },
  )
  if err != nil {
    panic(falcon.ErrorExplain(err))
  }

  fmt.Printf("%+v\n", response.Payload)
}

TypeScript

import { FalconClient } from "crowdstrike-falcon";

const client = new FalconClient({
  cloud: process.env.FALCON_CLOUD!,
  clientId: process.env.FALCON_CLIENT_ID!,
  clientSecret: process.env.FALCON_CLIENT_SECRET!,
});

const response = await client.zeroTrustAssessment.getAuditV1();

console.log(response);

Rust

use rusty_falcon::apis::zero_trust_assessment_api::get_audit_v1;
use rusty_falcon::easy::client::FalconHandle;

#[tokio::main]
async fn main() {
    let falcon = FalconHandle::from_env().await.expect("Could not authenticate");

    let response = get_audit_v1(&falcon.cfg).await.expect("API call failed");  // configuration

    println!("{:?}", response);
}

Ruby

require "crimson-falcon"

Falcon.configure do |config|
  config.client_id = ENV["FALCON_CLIENT_ID"]
  config.client_secret = ENV["FALCON_CLIENT_SECRET"]
  config.cloud = ENV["FALCON_CLOUD"]
end

api = Falcon::ZeroTrustAssessment.new

response = api.get_audit_v1

puts response

Responses

200 OK

[
  {
    "average_overall_score": 0.0,
    "cid": "string",
    "num_aids": 0,
    "platforms": []
  }
]

403 Forbidden

{
  "errors": [
    {
      "code": 0,
      "id": "string",
      "message": "string"
    }
  ],
  "meta": {
    "pagination": {
      "limit": 0,
      "offset": 0,
      "total": 0
    },
    "powered_by": "string",
    "query_time": 0.0,
    "trace_id": "string",
    "writes": {
      "resources_affected": 0
    }
  }
}

404 One or more of the specified agent IDs is not found.

{
  "errors": [
    {
      "code": 0,
      "id": "string",
      "message": "string"
    }
  ],
  "meta": {
    "pagination": {
      "limit": 0,
      "offset": 0,
      "total": 0
    },
    "powered_by": "string",
    "query_time": 0.0,
    "quota": {
      "total": 0,
      "used": 0
    },
    "trace_id": "string",
    "writes": {
      "resources_affected": 0
    }
  },
  "resources": [
    {
      "average_overall_score": 0.0,
      "cid": "string",
      "num_aids": 0,
      "platforms": []
    }
  ]
}

429 Too Many Requests

{
  "errors": [
    {
      "code": 0,
      "id": "string",
      "message": "string"
    }
  ],
  "meta": {
    "pagination": {
      "limit": 0,
      "offset": 0,
      "total": 0
    },
    "powered_by": "string",
    "query_time": 0.0,
    "trace_id": "string",
    "writes": {
      "resources_affected": 0
    }
  }
}

500 Unexpected Error

{
  "errors": [
    {
      "code": 0,
      "id": "string",
      "message": "string"
    }
  ],
  "meta": {
    "pagination": {
      "limit": 0,
      "offset": 0,
      "total": 0
    },
    "powered_by": "string",
    "query_time": 0.0,
    "trace_id": "string",
    "writes": {
      "resources_affected": 0
    }
  }
}