Skip to main content
Skip table of contents

Search API

This guide explains how to authenticate to the API, construct search queries, and interpret response data. It also provides practical examples for common use cases such as identifying high-severity findings, retrieving certificates from specific hosts, and generating compliance summaries across multiple sources.

1. Overview

This guide describes the Search API exposed by the AgileSec Analytics Server, which allows developers to query cryptographic events stored in the AgileSec Analytics index.

2. API Access

2.1 Entry Point

Base URL (entry point)

CODE 
https://<agilesec-plantform-url>/searchdb

2.2 Authentication

Access requires authentication. You can use existing users, create new users, or configure other authentication mechanisms.

2.3 curl Example

Example of executing a query and returning all documents:

JSON 
curl --insecure -u <login>:<password> \
  -H 'Content-Type: application/json' \
  -POST "https://<yourserver>/searchdb/isg-event*/_search" \
  -d '{"query": {"match_all": {}}}'

2.4 Developer UI

You can test queries from the embedded developer UI by going to Advanced Analytics Dashboard -> Left Menu → Dev Tools

3. API Queries

3.1 Search Structure

A Search API call is composed of:

  1. The index to query

  2. The /_search API

  3. Optional parameters like from and size for pagination

  4. The query used to filter events.

3.2 Index Name Structure

All index names are prefixed with the organization domain.

  • Org domain: kf-agilesec.com

  • Org index prefix: kf-agilesec_com (replace . with _)

As a result, all indexes follow this pattern:

kf-agilesec_com-*

Example: kf-agilesec_com-isg-event*

Note: All examples in this guide use the placeholder <org-index-prefix>. Replace it with your organization’s index prefix.

Run the following query to view the list of all indexes you have access to:

CODE 
GET /_resolve/index/<org-index-prefix>-*

For example, if your organization domain is kf-agilesec.com, run:

CODE 
GET /_resolve/index/kf-agilesec_com-*

3.3 Simple Search Example

The following search will return the first 200 cryptographic events present within the index "<org-index-prefix>-isg-event-*" without filtering. 

JSON 
GET <org-index-prefix>-isg-event-*/_search?from=0&size=200
{
  "query": { "match_all": {} }
}

3.4 Query fields

All fields present in the AgileSec Analytics index can be used to build queries, see AgileSec Cryptographic Data Fields.

Response format (high level)

The query returns cryptographic events as JSON in the hits.hits array. Each element in hits.hits includes an _source field that contains the event JSON.

JSON 
{
  "took" : 10,
  "timed_out" : false,
  "_shards" : {
    "total" : 6,
    "successful" : 6,
    "skipped" : 0,
    "failed" : 0
  },
  "hits" : {
    "total" : {
      "value" : 32,
      "relation" : "eq"
    },
    "max_score" : 2.0,
    "hits" : [
      {
        "_index" : "<org-index-prefix>-isg-event-certificate-2022",
        "_id" : "8f6e8fe9868c8049a95d8363eec201d77e9028bf7a757bc2389e19670b842422",
        "_score" : 2.0,
        "_source" : {
          "x509" : {
            "key_usage" : "Digital Signature, Certificate Sign, CRL Sign",
            "not_before" : "2015-10-01T22:35:15.000+0000",
            "subject" : {
              "country" : null,
              "state_or_province" : null,
              "organization" : null,
              "locality" : null,
              "common_name" : "isglocal-ISGTORDCW001-CA",
              "organizational_unit" : null
            },
            "public_key_curve" : "BFDFE89BA2CA6F3BC6F5...466C4353",
            "usage" : "Intermediate CA",
            "serial_number" : "7F80B56D1074919E44D9C744F2079B2F",
            "basic_constraints_is_ca" : true,
            "issuer" : {
              "country" : null,
              "state_or_province" : null,
              "organization" : null,
              "locality" : null,
              "common_name" : "isglocal-ISGTORDCW001-CA",
              "organizational_unit" : null
            },
            "fingerprint_sha256" : "59acdc396bd24b64b0132..1cf411e3b4c4e1dcad256",
            "not_after" : "2035-10-01T22:45:15.000+0000",
            "public_key_exponent" : "010001",
            "fingerprint_sha1" : "3aa30d436ef94d33897c019b89ad06c0e2a8ea2e",
            "public_key_algorithm" : "rsaEncryption",
            "signature_algorithm" : "RSA-SHA256",
            "public_key_size" : 2048,
            "self_signed" : true,
            "extended_key_usage" : null
          },
          "file" : {
            "hash_sha256" : "fea26249d9ee96698e9209605b5c0da9da324c76ab08ccc8",
            "path" : "file:///C://AgileScan/testwindowsP7.p7b",
            "extension" : "p7b",
            "name" : "testwindowsP7.p7b",
            "directory" : "file:///C://AgileScan/"
          },
          "@timestamp" : "2022-08-29T08:41:31.294966643+00:00",
          "file.type" : [
            "File Certificate"
          ],
          "host" : {
            "ipaddress" : null,
            "name" : "DESKTOP-PC9NH83"
          },
          "policy.priority" : [
            "Normal"
          ],
          "sensor" : {
            "type" : "ISG Sensor"
          },
          "source" : {
            "name" : "DESKTOP-PC9NH83",
            "type" : "Host"
          },
          "test.cert.type" : "Enterprise Certificate",
          "object" : {
            "summary" : "Certificate: isglocal-ISGTORDCW001-CA-RSA-SHA256",
            "uid" : "8f6e8fe9868c8049a95d8363eec201d77e9028bf7a757bc2389e19670b842422",
            "fingerprint" : "59acdc396bd24b64...f411e3b4c4e1dcad256",
            "location" : "DESKTOP-PC9NH83:file:///C://AgileScan/testwindowsP7.p7b",
            "type" : "X.509 Certificate"
          }
        }
      }
    ]
  }
}

3.5 Testing the API

You can test the API directly from the Dev Tool in the Advanced Dashboard.

image-20260215-060220.png

4. Example Queries

4.1 Get unique sources

This query retrieves the list of unique sources of type host and network with a last scan date of now-30 days.

JSON 
GET <org-index-prefix>-isg-event-*/_search
{
  "query": {
    "bool": {
      "must": [
        { "terms": { "source.type": ["host", "network"] } },
        { "range": { "@timestamp": { "gte": "now-30d" } } }
      ]
    }
  },
  "aggs": {
    "source": {
      "terms": { "field": "source.name.keyword", "size": 100000 }
    }
  },
  "_source": false,
  "size": 0
}

4.2 Compliance issues by sources

This query retrieves the list of unique sources and related compliance issues. It includes specific filter for not low priority (priority_score >= 2) and for findings found last 360 days. 

JSON 
POST <org-index-prefix>-isg-event-*/_search?track_total_hits=true
{
  "query": {
    "bool": {
      "must": [
        { "match": { "source.type": "host" } },
        { "range": { "@timestamp": { "gte": "now-360d" } } },
        { "range": { "policy.priority_score": { "gte": 2 } } }
      ]
    }
  },
  "aggs": {
    "unique sources": {
      "terms": {
        "field": "source.name.keyword",
        "order": { "_count": "desc" },
        "size": 100
      },
      "aggs": {
        "unique policy flags": {
          "terms": {
            "field": "policy.flag.keyword",
            "order": { "_count": "desc" },
            "size": 50
          }
        }
      }
    }
  },
  "size": 0
}

4.3 Get all certificates

This query gets all X509 Certificates and returns a total of 100 documents.

JSON 
GET <org-index-prefix>-isg-event-*/_search
{
  "query": {
    "bool": {
      "must": [
        { "match": { "object.type": "Certificate" } }
      ]
    }
  },
  "size": 100
}

4.4 Get all certificates, return only selected fields

This query gets all X509 Certificates, returns 100 documents and only the given specific "fields". 

JSON 
GET <org-index-prefix>-isg-event-*/_search
{
  "query": {
    "bool": {
      "must": [
        {"match": {"object.type": "Certificate"}}
      ]
    }
  }, 
  "fields": ["x509.subject.common_name", "host.name.keyword", "policy.flag.keyword"],
  "_source": false,
  "size": 100
}

4.5 Get high-severity Certificates from a specific host

This query gets all X509 Certificates that have a score of 3 (high) and from the given Host Name. It returns 100 documents and only the given specific "fields". 

JSON 
GET <org-index-prefix>-isg-event-*/_search
{
  "query": {
    "bool": {
      "must": [
        {"match": {"object.type": "Certificate"}},
        {"match": {"policy.severity_score": "3"}},
        {"match": {"host.name.keyword": "LAPTOP-HS9RI16D"}}
      ]
    }
  }, 
  "fields": ["x509.subject.common_name", "host.name.keyword", "policy.flag.keyword"],
  "_source": false,
  "size": 100
}

4.6 Get All End-Entity Certificates with a high severity from a specific host

This query gets all X509 Certificates that have a score of 3 (high) and from the given Host Name. X.509 Certificates must be End-Entity and Not "Code Signing, Timestamp or OCSP". It returns 100 documents and only the given specific "fields". 

JSON 
GET <org-index-prefix>-isg-event-*/_search
{
  "query": {
    "bool": {
      "must": [
        {"match": {"object.type": "Certificate"}},
        {"match": {"policy.severity_score": "3"}},
        {"match": {"host.name.keyword": "LAPTOP-HS9RI16D"}},
        {"match": {"x509.usage": "End-Entity"}}
      ],
      "must_not": [
        {"terms": {"x509.usage_details.keyword": ["Code Signing", "Timestamp", "OCSP"]}}
      ]
    }
  }, 
  "fields": ["x509.subject.common_name", "host.name.keyword"],
  "_source": false,
  "size": 100
}

4.7 Query algorithms list

Get Algorithms that are matching with the given algorithms' keywords.

JSON 
GET <org-index-prefix>-isg-event-*/_search?from=0&size=100
{
  "query": {
    "bool": {
      "must": [{ "terms": { "algorithm.name.keyword": ["rc2","siphash","3des","blowfish"]}}],
      "filter": {
        "bool": {
          "must": [{"match": {"object.type": "Algorithm"}}]
        }
      }
    }
  }
}

5. Query Results

The platform stores different event types in different indexes (examples below), but the response shape is consistent: hits.hits[] includes _source.

5.1 X.509 Certificates

The following represents the results of a X.509 Certificate Query:

JSON 
{
  "took" : 10,
  "timed_out" : false,
  "_shards" : {
    "total" : 6,
    "successful" : 6,
    "skipped" : 0,
    "failed" : 0
  },
  "hits" : {
    "total" : {
      "value" : 32,
      "relation" : "eq"
    },
    "max_score" : 2.0,
    "hits" : [
      {
        "_index" : "<org-index-prefix>-isg-event-certificate-2023",
        "_id" : "8f6e8fe9868c8049a95d8363eec201d77e9028bf7a757bc2389e19670b842422",
        "_score" : 2.0,
        "_source" : {
          "x509" : {
            "key_usage" : "Digital Signature, Certificate Sign, CRL Sign",
            "not_before" : "2015-10-01T22:35:15.000+0000",
            "subject" : {
              "country" : null,
              "state_or_province" : null,
              "organization" : null,
              "locality" : null,
              "common_name" : "isglocal-ISGTORDCW001-CA",
              "organizational_unit" : null
            },
            "public_key_curve" : "BFDFE89BA2CA6F3BC6F5...466C4353",
            "usage" : "Intermediate CA",
            "serial_number" : "7F80B56D1074919E44D9C744F2079B2F",
            "basic_constraints_is_ca" : true,
            "issuer" : {
              "country" : null,
              "state_or_province" : null,
              "organization" : null,
              "locality" : null,
              "common_name" : "isglocal-ISGTORDCW001-CA",
              "organizational_unit" : null
            },
            "fingerprint_sha256" : "59acdc396bd24b64b0132..1cf411e3b4c4e1dcad256",
            "not_after" : "2035-10-01T22:45:15.000+0000",
            "public_key_exponent" : "010001",
            "fingerprint_sha1" : "3aa30d436ef94d33897c019b89ad06c0e2a8ea2e",
            "public_key_algorithm" : "rsaEncryption",
            "signature_algorithm" : "RSA-SHA256",
            "public_key_size" : 2048,
            "self_signed" : true,
            "extended_key_usage" : null
          },
          "file" : {
            "hash_sha256" : "fea26249d9ee96698e9209605b5c0da9da324c76ab08ccc8",
            "path" : "file:///C://AgileScan/testwindowsP7.p7b",
            "extension" : "p7b",
            "name" : "testwindowsP7.p7b",
            "directory" : "file:///C://AgileScan/"
          },
          "@timestamp" : "2022-08-29T08:41:31.294966643+00:00",
          "file.type" : [
            "File Certificate"
          ],
          "host" : {
            "ipaddress" : null,
            "name" : "DESKTOP-PC9NH83"
          },
          "policy.priority" : [
            "Normal"
          ],
          "sensor" : {
            "type" : "ISG Sensor"
          },
          "source" : {
            "name" : "DESKTOP-PC9NH83",
            "type" : "Host"
          },
          "test.cert.type" : "Enterprise Certificate",
          "object" : {
            "summary" : "Certificate: isglocal-ISGTORDCW001-CA-RSA-SHA256",
            "uid" : "8f6e8fe9868c8049a95d8363eec201d77e9028bf7a757bc2389e19670b842422",
            "fingerprint" : "59acdc396bd24b64...f411e3b4c4e1dcad256",
            "location" : "DESKTOP-PC9NH83:file:///C://AgileScan/testwindowsP7.p7b",
            "type" : "X.509 Certificate"
          }
        }
      }
    ]
  }
}

5.2 Cryptographic Keys

The following represents the results of a Key Query:

JSON 
{
  "took" : 3,
  "timed_out" : false,
  "_shards" : {
    "total" : 6,
    "successful" : 6,
    "skipped" : 0,
    "failed" : 0
  },
  "hits" : {
    "total" : {
      "value" : 687,
      "relation" : "eq"
    },
    "max_score" : 1.0,
    "hits" : [
      {
        "_index" : "<org-index-prefix>-isg-event-key-2023",
        "_id" : "a9f856862fdc8ebb70b5a3d6510dfc646dbd451c35431de3054a86098f9dc3ee",
        "_score" : 1.0,
        "_source" : {
          "policy.severity_score" : 3,
          "file" : {
            "path" : "file:///usr/lib64/libgnutls.so.30.28.0",
            "extension" : "0",
            "name" : "libgnutls.so.30.28.0",
            "directory" : "file:///usr/lib64"
          },
          "@timestamp" : "2022-08-29T08:12:05.549088697+00:00",
          "policy.flag" : [
            "key_hardcoded"
          ],
          "host" : {
            "ipaddress" : "10.32.9.56",
            "name" : "isgtortan006"
          },
          "policy.priority" : [
            "Normal"
          ],
          "sensor" : {
            "type" : "Tanium Sensor"
          },
          "source" : {
            "name" : "isgtortan006",
            "type" : "Host"
          },
          "key" : {
            "size" : 2048,
            "is_encrypted" : false,
            "type" : "private",
            "algorithm" : "rsa"
          },
          "object" : {
            "summary" : "Key: private-rsa-2048",
            "uid" : "a9f856862fdc8ebb70b5a3d6510dfc646dbd451c35431de3054a86098f9dc3ee",
            "fingerprint" : "7f32e3bdcdb8524a6b22...6c4d51b18063bd",
            "location" : "isgtortan006:file:///usr/lib64/libgnutls.so.30.28.0",
            "type" : "Cryptographic Key"
          }
        }
      }
    ]
  }
}

5.3 Keystore

The following represents the results of a Keystore Query:

JSON 
{
  "took" : 3,
  "timed_out" : false,
  "_shards" : {
    "total" : 6,
    "successful" : 6,
    "skipped" : 0,
    "failed" : 0
  },
  "hits" : {
    "total" : {
      "value" : 208,
      "relation" : "eq"
    },
    "max_score" : 0.0019474202,
    "hits" : [
      {
        "_index" : "<org-index-prefix>-isg-event-keystore-2023",
        "_id" : "cacfefb756485c68a3797647a3d2b4489d1326b4c8da06eb214f2d2091a4d990",
        "_score" : 0.0019474202,
        "_source" : {
          "file" : {
            "hash_sha256" : "22788256E7B28FEA9BD33325D135A66DBF2B7FB68E1FA699",
            "path" : "file:///C://AgileScan/AgilescanCert.p12",
            "extension" : "p12",
            "name" : "AgilescanCert.p12",
            "directory" : "file:///C://AgileScan/"
          },
          "@timestamp" : "2022-08-29T08:41:31.288217488+00:00",
          "file.type" : [
            "Key File"
          ],
          "host" : {
            "ipaddress" : null,
            "name" : "DESKTOP-PC9NH83"
          },
          "policy.priority" : [
            "Normal"
          ],
          "sensor" : {
            "type" : "ISG Sensor"
          },
          "keystore" : {
            "type" : "file-pfx"
          },
          "source" : {
            "name" : "DESKTOP-PC9NH83",
            "type" : "Host"
          },
          "object" : {
            "summary" : "Keystore: file-pfx",
            "uid" : "cacfefb756485..b214f2d2091a4d990",
            "fingerprint" : "3042a5bd9c27c3de97..8905f93a12b7db",
            "location" : "DESKTOP-PC9NH83:file:///C://AgileScan/dAgilescanCert.p12",
            "type" : "Keystore"
          }
        }
      }
    ]
  }
}

5.4 Libraries

The following represents the results of a Library Query:

JSON 
{
  "took" : 3,
  "timed_out" : false,
  "_shards" : {
    "total" : 6,
    "successful" : 6,
    "skipped" : 0,
    "failed" : 0
  },
  "hits" : {
    "total" : {
      "value" : 936,
      "relation" : "eq"
    },
    "max_score" : 5.3149083E-4,
    "hits" : [
      {
        "_index" : "<org-index-prefix>-isg-event-library-2023",
        "_id" : "be5a7851c9bbe63d9fc14855c1f9e307468715abd784e64af19516413ea0928f",
        "_score" : 5.3149083E-4,
        "_source" : {
          "file" : {
            "hash_sha256" : "70A9E8282AEDE79B46F8D3065744454A42E8BF292D1E4DEA",
            "path" : "file:///C://AgileScan/libcrypto.so.1.1",
            "extension" : "1",
            "name" : "libcrypto.so.1.1",
            "directory" : "file:///C://AgileScan/"
          },
          "library" : {
            "name" : "symbol-openssl",
            "version" : "1"
          },
          "@timestamp" : "2022-08-29T08:41:28.881249561+00:00",
          "host" : {
            "ipaddress" : null,
            "name" : "DESKTOP-PC9NH83"
          },
          "policy.priority" : [
            "Normal"
          ],
          "sensor" : {
            "type" : "ISG Sensor"
          },
          "source" : {
            "name" : "DESKTOP-PC9NH83",
            "type" : "Host"
          },
          "object" : {
            "summary" : "Library: symbol-openssl-1",
            "uid" : "be5a7851c9bbe63d9fc14855c1f9e307468715abd784e64af19516413ea0928f",
            "fingerprint" : "f262d8e998cab40d8..1aebe4793ca771f41",
            "location" : "DESKTOP-PC9NH83:file:///C://AgileScan/libcrypto.so.1.1",
            "type" : "Cryptographic Library"
          }
        }
      }
    ]
  }
}

5.5 Algorithm

The following represents the results of an Algorithm Query:

JSON 
{
  "took" : 6,
  "timed_out" : false,
  "_shards" : {
    "total" : 6,
    "successful" : 6,
    "skipped" : 0,
    "failed" : 0
  },
  "hits" : {
    "total" : {
      "value" : 10000,
      "relation" : "gte"
    },
    "max_score" : 2.3282075E-5,
    "hits" : [
      {
        "_index" : "<org-index-prefix>-isg-event-algorithm-2023",
        "_id" : "e0ea1f4e44ba1d9e6bcb80cff3d6236a5884e0fae39ab078c1422b6f3366d328",
        "_score" : 2.3282075E-5,
        "_source" : {
          "policy.severity_score" : 1,
          "file" : {
            "hash_sha256" : "7EAE02D0115D53F0D67D42A2DF6CCA5A28420B3BEDEEB806",
            "path" : "file:///C://AgileScan/ngx_.so",
            "extension" : "so",
            "name" : "ngx_.so",
            "directory" : "file:///C://AgileScan/"
          },
          "@timestamp" : "2022-08-29T08:41:29.063772801+00:00",
          "policy.flag" : [
            "algorithm_secure"
          ],
          "host" : {
            "ipaddress" : null,
            "name" : "DESKTOP-PC9NH83"
          },
          "policy.priority" : [
            "Normal"
          ],
          "sensor" : {
            "type" : "ISG Sensor"
          },
          "source" : {
            "name" : "DESKTOP-PC9NH83",
            "type" : "Host"
          },
          "object" : {
            "summary" : "Algorithm: hashfunc-sha2-256",
            "uid" : "e0ea1f4e44ba1d9e6bcb80cff3d6236a5884e0fae39ab078c1422b6f3366d328",
            "fingerprint" : "d93760bf80a251f7e85b31..be27e4a345fa1245a0e02ea1",
            "location" : "DESKTOP-PC9NH83:file:///C://AgileScan/ngx_.so",
            "type" : "Algorithm"
          },
          "algorithm" : {
            "function" : "hashfunc",
            "name" : "sha2-256",
            "type" : "implementation"
          }
        }
      }
    ]
  }
}

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close