Undocumented fields for Secure Endpoint Actions v1/events endpoint

[chwelt88]

Hello all, 

I am experimenting with the Cisco secure endpoint v1/events GET API endpoint  , 

and I a get response schema which includes additional fields on the data root level which are not documented on the official API reference, such as an array of vulnerabilities and a command_line JSON object. 

Any reference for these fields, and/or if they can be relied on as valid fields in the schema response ? No vulnerabilities field on the response schema documenation

[Matthew Franks]

These fields are likely due to additional functionality that was added after this API call was created. I'll get a documentation bug filed so someone can get it updated.  Thank you for brining it to our attention!

-Matt

[chwelt88]

@Math Thanks allot! 

Highly appreciated! 

[Matthew Franks · Accepted solution]

After speaking to the developers I have a bit of clarification. The schema contains all of the fields that will be returned for any event. There can be additional fields for some events, but not all of them will contain these additional fields so they are not documented in the schema. Please let me know if that makes sense or if you have further questions.

-Matt

[chwelt88]

@Matthew Franks Thank you so much for checking this out.

It does make some sense, though, as a customer, I would have preferred of course to have the complete response schema in advance, including the fields that are optional and may be returned only for some event types. I believe this is supported on OAS 3.0 via the required property, for distinguishing between optional and required fields. For illustration, I've added to the event_oas_yaml a required property under the data items of the response schema object, listing as an example all the currently listed properties, and added an additional command_line property which is now in the schema, but is NOT defined under the list of required properties of the data item object: 

      responses:
        "200":
          content:
            application/json:
              schema:
                type: object
                properties:
                  version:
                    type: string
                  metadata:
                    $ref: "#/components/schemas/Metadata"
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                        timestamp:
                          type: integer
                        timestamp_nanoseconds:
                          type: integer
                        date:
                          type: string
                          format: date-time
                        event_type:
                          type: string
                        event_type_id:
                          type: integer
                        detection:
                          type: string
                        detection_id:
                          type: string
                        connector_guid:
                          type: string
                        group_guids:
                          type: array
                          items:
                            type: string
                        severity:
                          type: string
                        computer:
                          type: object
                          properties:
                            connector_guid:
                              type: string
                            hostname:
                              type: string
                            external_ip:
                              type: string
                              format: ip-address
                            user:
                              type: string
                            active:
                              type: boolean
                            network_addresses:
                              type: array
                              items:
                                type: object
                                properties:
                                  ip:
                                    type: string
                                    format: ip-address
                                  mac:
                                    type: string
                                    format: style
                            links:
                              type: object
                              properties:
                                computer:
                                  type: string
                                  format: uri
                                trajectory:
                                  type: string
                                  format: uri
                                group:
                                  type: string
                                  format: uri
                        file:
                          type: object
                          properties:
                            disposition:
                              type: string
                            file_name:
                              type: string
                            file_path:
                              type: string
                              format: style
                            identity:
                              type: object
                              properties:
                                sha256:
                                  type: string
                                sha1:
                                  type: string
                                md5:
                                  type: string
                            parent:
                              type: object
                              properties:
                                process_id:
                                  type: integer
                                disposition:
                                  type: string
                                file_name:
                                  type: string
                                identity:
                                  type: object
                                  properties:
                                    sha256:
                                      type: string
                                    sha1:
                                      type: string
                                    md5:
                                      type: string
                        tactics:
                          type: array
                          items:
                            type: string
                        techniques:
                          type: array
                          items:
                            type: string
                        command_line:
                          type: object
                          properties:
                            arguments:
                              type: string
                      required:
                        - id 
                        - timestamp 
                        - timestamp_nanoseconds
                        - date
                        - event_type
                        - event_type_id
                        - detection
                        - detection_id
                        - connector_guid
                        - group_guids
                        - severity
                        - computer
                        - file
                        - tactics
                        - techniques

If we examine the updated yaml on a swagger editor , we can see the properties that were defined as required are marked with a red asterisk while the new added optional property - command_line, which is not under the required list, is without it: 

So if it was up to me to maintain the API docs, I would have probably updated the Swagger accordingly & adding additional examples that cover the additional fields as well, documenting their content, semantics, and the event types they are expected to be included for. 

On any case, your answer helped allot, and I highly appreciate your effort to help. 

Thank you very much.