Search API Migration Guide v3 to 3.5

This guide is for developers who query AgileSec data via the OpenSearch API. It covers every field path, value, and type change between v3 and v3.5 that can break an existing query, filter, or aggregation.

Overview

The guide is organized in four parts. What Changed gives a high-level structural summary. Quick Reference is a complete flat lookup table for fast find-and-replace across all field names. The Field sections cover each field group with context, notes, and examples for the changes requiring more than a simple rename. Migration Considerations highlights the changes most likely to cause issues when updating queries.

What Changed

Flat → nested paths. The biggest change in v3.5 is the document structure went from flat top-level fields to nested containers. Most fields now live under observation.*, crypto.*, or analysis.*. Any query referencing the old flat paths will silently return no results.

Value and type changes. Some fields changed type or value format in addition to moving. These are the ones most likely to cause silent query failures – see the ⚠️ rows in Index Name Changes and Quick Reference for the full list.

Index Name Changes

Index names follow a new naming convention in v3.5. The org domain portion of the index name is preserved but the surrounding pattern has changed: the old -isg-event- infix is replaced with the prefix agilesec. and .v3.event- infix. Note the certificate index is also renamed from certificate to x509, and the source code index is renamed from sourcecode to algorithm.

When migrating index names, use the table below, replacing <org> with your org domain with dots replaced by underscores (e.g. example.com → example_com).

Quick Reference – All Field Renames

Update your OpenSearch queries by replacing the field names in the left column with those in the right. Fields marked ⚠️ have a value or type change in addition to being renamed – pay close attention to these as they can cause silent query failures even after updating the path. Fields marked 🔵 only require a path prefix or field name rename (find-and-replace).

A complete flat list of every field rename. Use this as a find-and-replace reference to update all query field paths in one pass.

Observation Fields

Fields describing the non-cryptographic context of a finding: where it was found, what sensor found it, and what file it was in. In v3 these were flat top-level objects. In v3.5 they are all nested under observation.*.

Sensor

• All sensor fields are now unified under observation.sensor.*.

• source.subtype is the authoritative sensor type, moving to observation.sensor.type – not observation.source.type.

• Old generic values like "ISG Sensor" and "ISG Network Sensor" are replaced with specific types e.g. "Host Filesystem", "GIT Repository", "Network Sensor".

• sensorId → observation.sensor.sid, executionId → observation.sensor.eid.

Source

• All source-related fields are consolidated under observation.source.*.

• host.*, network.interface_ip, process.name, application.name, and repository.branch are all absorbed into observation.source.*.

• object.location and object.location_short move from the object block to observation.source.* with format changes – see ⚠️ rows in the Quick Reference.

File

• All file fields move from flat file.* to observation.file.*.

• file.path and file.directory have the file:/// URI prefix stripped; they are now bare absolute paths.

• file.metadata.* sub-fields are promoted directly to observation.file.*, no longer nested under metadata.

• file.metadata.permission is renamed to observation.file.permissions.

Object Fields

Fields describing the high-level summary of a finding: type, fingerprint, unique ID, and resolution status. The objectblock path is unchanged but several field values have changed.

Object

• object.resolution.status (string) is replaced by object.resolution.resolved (boolean); "open" → false, "resolved" → true.

• object.fingerprint is now lowercase hex.

• object.location and object.location_short have moved to observation.source.*.

• object.encoded is removed entirely.

Crypto Payload Fields

Fields describing the cryptographic details of a finding. In v3 each crypto type was a flat top-level object (e.g. algorithm, x509, key). In v3.5 all are nested under crypto.<type>.*.

Algorithm

• All algorithm fields move from flat algorithm.* to crypto.algorithm.*.

• algorithm.type is renamed to crypto.algorithm.purpose.

• algorithm.function is now enum-validated; free-text values like "ecc" are replaced with "" or the correct enum value, e.g., "key_agreement".

Certificate (x509)

• All x509 fields move from flat x509.* to crypto.x509.*.

  • x509.not_after → crypto.x509.exp, x509.not_before → crypto.x509.nbf.

• x509.key_usage and x509.extended_key_usage change from comma-separated strings to arrays inside structured extension objects. Queries on these fields require logic changes, not just a rename.

• Public key fields (public_key_algorithm, public_key_size, public_key_exponent, public_key_curve) are now nested inside crypto.x509.public_key.*.

• subject.* and issuer.* field values are now arrays – null fields are omitted.

• subject.distinguished_name and issuer.distinguished_name are removed.

Key

• All key fields move from flat key.* to crypto.key.*.

• key.algorithm values are now uppercase, e.g., "rsa" → "RSA".

• key.hash_sha256 is renamed to crypto.key.fingerprint_sha256 and is now lowercase hex.

Keystore

• keystore.* moves to crypto.keystore.* with no value changes; path prefix update only.

Token

• All token fields move from flat token.* to crypto.token.*.

• The payload is split: the seven RFC 7519 standard claims (iss, sub, aud, exp, nbf, iat, jti) stay at crypto.token.payload.*.

• All other custom claims (e.g. email, roles, tenant_id) move to crypto.token.payload.other.*; queries on custom claims must add .other. to the path.

Library

• library.* moves to crypto.library.* with no value changes; path prefix update only.

Protocol

• All protocol fields move from flat protocol.* to crypto.protocol.*.

• network.cipher_suite, network.protocol_name, and network.key_agreement are consolidated into crypto.protocol.*; both old paths now map to the same new fields.

Analysis Fields

Fields describing policy evaluation, priority scoring, post-quantum assessment, and cryptographic strength analysis of a finding. In v3, policy.*, policy_pqc.*, and priority.* existed as flat top-level fields. analysis.cryptography is entirely new in v3.5.

Policy

• All policy fields move from flat policy.* to analysis.policy.* with no value changes; path prefix update only.

Policy PQC

• Moved from flat policy_pqc.* to analysis.policy_pqc.* with no value changes; path prefix update only.

Priority

• Moved from flat priority.* to analysis.priority.* with no value changes; path prefix update only.

Cryptography (New)

• Entirely new in v3.5 – no v3 equivalent.

• analysis.cryptography.* contains cryptographic analysis of the finding based on its object type: certificate, key, protocol, algorithm, etc..

• Provides a unified cryptographic view across all object types, covering the underlying cryptographic properties regardless of how the finding was collected.

Migration Considerations

These are the changes most likely to cause issues when updating queries. Unlike path renames, which will throw an error or return no results, these can silently return wrong or incomplete data.

Silent query failures from value and type changes. When a field changes type or value format, OpenSearch will not throw an error: the query will simply return zero results. The highest-risk changes are object.resolution.status (string → boolean), key.algorithm casing ("rsa" → "RSA"), key.hash_sha256 casing (now lowercase), and object.fingerprint casing (now lowercase).

source.subtype moves to sensor, not source. This is the most non-obvious redirect in the migration. source.subtype becomes observation.sensor.type – not observation.source.type as you might expect. Any filter or aggregation on sensor type currently using source.subtype needs to point to the sensor block, not the source block.

key_usage and extended_key_usage require query logic changes, not just a rename. These fields change from a comma-separated string to an array inside a structured extension object. A query like match: { x509.key_usage: "Digital Signature" } must become term: { crypto.x509.extensions.key_usage.value: "Digital Signature" }. This is a structural change to your query, not a field rename.

Token custom claims require knowing your RFC 7519 fields. Standard claims (iss, sub, aud, exp, nbf, iat, jti) stay at payload.*. All other claims move to payload.other.*. If you query any custom JWT fields, you need to identify which ones are non-standard and add .other. to their path. Failing to do so will silently return no results.