Public API v2

Added

  • Added new entity types:
    • Attack Pattern
    • Location
    • Malware
    • Tool
    • Infrastructure
    • Intrusion set
    • Identity
    • Malware Analysis
  • Added GET /api/v2/aggregations/entities/counts to get count entities aggregation on the field value usages, for specific set of fields.
  • Added GET /api/v2/content-blocks to list content blocks.
  • Added GET /api/v2/content-blocks/<id> to get content block by id.

Changes

  • /relationships endpoint has been updated
    • The /api/v2/relationships endpoints accept new fields: data.description,
      meta.estimated_threat_start_time, meta.estimated_threat_end_time and
      meta.tlp_color.
    • Added PATCH /api/v2/relationships/<uuid> to update a single entity relation.
    • Added PUT /api/v2/relationships to allow bulk upserting of entity relations.
    • A response from the endpoint /api/v2/relationships can return strict_stix_1 and strict_stix_2 fields.
  • Performance change: endpoints querying the total count in PostgreSQL (i.e. GET /api/v2/observables/) will return an estimated count of total entries if there are more entries than a set number. Default is 10_000.
  • /rules/entities endpoint has been updated
    • Added remove_taxonomies field on entity rule, a list of taxonomies removed from the matched entity if the rule has remove_tags action.
    • Added remove_tags field on entity rule, a list of tags removed from the matched entity if the rule has remove_tags action.
    • Added eiqjson2_entity_type field on entity rule, which is a required target type for conversion if the rule has convert_to_eiqjson2 action.
  • It is possible to attach attachments on /api/v2/entities to any entity type and
    not only report.
  • For /api/v2/entities, as a security measure, it is not possible to reference an
    attachment as an image <img src="/private/entity-attachments/<id>/download" /> in
    data.description or data.short_description without having that attachment also
    related in attachments. If this is not respected a 400 is returned.
  • The /api/v2/tickets endpoint now accepts the blank value "" for status. If no status is
    provided, then "OPEN" is the default instead of "".

Breaking Changes

  • PUT/POST/PATCH /api/v2/relationships now requires a sources property which accepts a list of source ids. By providing a list of source ids, you can define the relationship sources.

  • The /api/v2/relationships endpoints expect that data.key better aligns with our new model based on STIX 2.1. The value of this property must be in ASCII, no longer than 256 characters and is limited to characters a–z (lowercase ASCII), 0–9, and hyphen (-).

  • The /api/v2/relationships endpoints expect that data.subtype can only accept stix_update_of value.

  • The type of an entity is now nested inside the data dictionary.

    Previously:

    {
        "type": "indicator",
        "data": {
            "title": "Entity Old",
            "description": "Test entity with old schema"
        },
        "meta": {}
    }
    

    Now:

    {
        "data": {
            "type": "indicator",
            "title": "Entity New",
            "description": "Test entity with new schema"
        },
        "meta": {}
    }
    
  • The field data.source property of /api/v2/entities/rules is replaced with data.sources which contain an array of sources' ids which the rule applies to. If the array is empty, the rule is applied to all sources.

  • taxonomies field is renamed to add_taxonomies

  • overwrite_tags and overwrite_taxonomies query parameters are no longer supported

  • The payload of /api/v2/datasets requires at least one relationship for workspaces. The workspaces relationship field is also returned on the response.

  • The payload for a PUT request does not require a another nested data property.
    Previously:

    {
      "data": [{"data": {}}, {"data": {}}]
    }
    

    Now:

    {
      "data": [{}, {}]
    }
    
  • When filtering a GET request with the filter[<property>]=<value> query parameter, and where <value> must be a valid ID, now responds with a HTTP 400 error if <value> is not a valid ID. Previously, GET requests that attempt to filter with invalid IDs would ignore filter[<property>=<invalid_id> and respond with HTTP 200.
    E.g.: GET /api/v2/tickets?filter[entities]=1111 responds with a HTTP 400 error as filter[entities] expects a UUID.

  • The threat-actor entity type schema has changed. Requests sending payloads containing the older threat-actor entity type schema will be rejected with a400 error.

  • All entities types have at least two required fields: type and title

Fixes

  • EIQ-2022-0004: Issue where knowledge packs can be deleted via API by users with only read knowledge-packs permissions

  • Fixed issue where updating the contents of theattachmentsfield in requests to /api/v2/entities would not actually update that field.