Analysis Examples

CloudShark’s analysis API provides the ability to transform raw packet captures into JSON structured, data. This data can feed directly into monitoring dashboards, ticketing systems, and security platforms to provide tools with packet capture information, while providing access to the full file when more analysis is required to determine the root cause of an issue.

These examples use curl and the jq JSON parser to explore CloudShark analysis API.

In these below replace the following values:

• ${CLOUDSHARK_URL}: CloudShark Instance URL.
  • Example: https://cloudshark.local
• ${CAPTURE_ID}: CloudShark Session Capture ID.
  • Example: 711365563117
• ${API_TOKEN}: CloudShark API Token with PCAP analysis permission enabled.
  • Example: 82f2230b777174f098623e4a5203e4ce

Capture Summary

The /status API call, provides basic information such as the number of frames and the duration of the capture.

Example

Return the number of frames and duration of a capture file:

curl --request GET \
  --header "Authorization: ${API_TOKEN}" \
  --silent \
  --url "${CLOUDSHARK_URL}/api/v2/analysis/${CAPTURE_ID}/status" \
  | jq '{frames: .data.frames, duration: .data.duration}'

Output

{
  "frames": 6033,
  "duration": 403.430014
}

Top Talker

Using the /stats/endpoints API endpoint, you can find the host who sent the most traffic for a specific protocol.

Example

Returns the host that transmitted the most bytes for a protocol, and the number of frames and bytes sent:

curl --request GET \
  --header "Authorization: ${API_TOKEN}" \
  --silent \
  --url "${CLOUDSHARK_URL}/api/v2/analysis/${CAPTURE_ID}/stats/endpoints?protocol=${PROTO}" \
  | jq '.data.hosts | sort_by(.txb) | last | {host, txf, txb}'

In this example replace the following:

• ${PROTO}: Specific protocol to query such as:
  • eth
  • ip
  • ipv6
  • tcp
  • udp

Output

{
  "host": "204.79.197.200",
  "txf": 1079,
  "txb": 1193823
}

Protocols

The /stats/hierarchy API endpoint will return a breakdown of all of the protocols found in the capture file.

Example

Returns a breakdown of all of the leaf protocols found in the capture file:

curl --request GET \
  --header "Authorization: ${API_TOKEN}" \
  --silent \
  --url "${CLOUDSHARK_URL}/api/v2/analysis/${CAPTURE_ID}/stats/hierarchy" \
  | jq '[.data | .. | objects | select(has("proto")) | select(.protos == null) | {proto, frames, bytes}]'

Output

[
  {
    "proto": "dhcp",
    "frames": 7,
    "bytes": 2400
  },
  {
    "proto": "dns",
    "frames": 52,
    "bytes": 6424
  },
  {
    "proto": "tls",
    "frames": 81,
    "bytes": 46061
  }
]

TCP Analysis

TCP analysis details can be returned using the /packets/fields endpoint. One of the first details analysts need to know is the round trip time it takes to send packets between the two TCP endpoints which can be found in the field tcp.analysis.initial_rtt.

Example

Returns the TCP streams found in the capture with and the initial round trip time calculated during the three-way handshake:

curl --request GET \
  --header "Authorization: ${API_TOKEN}" \
  --silent \
  --url "${CLOUDSHARK_URL}/api/v2/analysis/${CAPTURE_ID}/packets/fields?fields=tcp.stream,ip.src,ip.dst,tcp.dstport,tcp.analysis.initial_rtt&filter=tcp.analysis.initial_rtt" \
  | jq '[.data.packets[].fields | {
  "stream": .["tcp.stream"],
  "src": .["ip.src"],
  "dst": .["ip.dst"],
  "dstport": .["tcp.dstport"],
  "initial_rtt": .["tcp.analysis.initial_rtt"]
}] | unique_by(.["stream"])'

Output

[
  {
    "stream": "0",
    "src": "192.168.1.145",
    "dst": "192.168.1.82",
    "dstport": "80",
    "initial_rtt": "0.037853000"
  },
  {
    "stream": "1",
    "src": "192.168.1.145",
    "dst": "10.9.0.2",
    "dstport": "443",
    "initial_rtt": "1.313298281"
  }
]

TLS/QUIC Hosts

The /packets/fields endpoint can extract the Server Name Indication (SNI) from TLS and QUIC handshakes using the tls.handshake.extensions_server_name field. This provides a list of all hosts contacted over encrypted connections.

Example

Returns a list of the unique server names found in TLS and QUIC handshakes:

curl  --request GET \
  --header "Authorization: ${API_TOKEN}" \
  --silent \
  --url "${CLOUDSHARK_URL}/api/v2/analysis/${CAPTURE_ID}/packets/fields?fields=tls.handshake.extensions_server_name&filter=tls.handshake.extensions_server_name" \
  | jq '[.data.packets[].fields["tls.handshake.extensions_server_name"]] | unique'

Output

[
  "support.qacafe.com",
  "qacafe.com"
]

DNS Audit

The /dns/lookups endpoint returns a list of all DNS lookups found in the capture file, including queries without responses and responses without queries.

Example

Returns all DNS lookups with their client address, query name, and query type:

curl --request GET \
  --header "Authorization: ${API_TOKEN}" \
  --silent \
  --url "${CLOUDSHARK_URL}/api/v2/analysis/${CAPTURE_ID}/dns/lookups" \
  | jq '[.data.lookups[] | {client, full_query, query_type}]'

Output

[
  {
    "client": "172.16.16.128",
    "full_query": "support.qacafe.com",
    "query_type": "A"
  },
  {
    "client": "172.16.16.128",
    "full_query": "support.qacafe.com",
    "query_type": "AAAA"
  }
]

Need Help?

These examples are just a starting point. The analysis API includes a variety of endpoints that can be combined to fit your specific use case. If you have questions about the API, or if there’s something you’d like to do that isn’t covered here, please contact support. We’d love to hear how you’re using the analysis API and what capabilities would be most useful to you.