340
edits
REST API description: Difference between revisions
no edit summary
No edit summary |
|||
| Line 1: | Line 1: | ||
This page describes how to access and use the REST API. It allows to post-process data with 3rd party systems. The Allegro web interface is itself based on this REST API and all displayed statistics can be extracted from the Allegro with this API. | This page describes how to access and use the REST API. It allows to post-process data with 3rd party systems. The Allegro web interface is itself based on this REST API and all displayed statistics can be extracted from the Allegro with this API. | ||
== General API Setup == | == General API Setup == | ||
| Line 34: | Line 33: | ||
The URL of the API call is the first argument. It is recommended to enclose the API call with the character ' to avoid replacing the argument ( unless you need to replace parts of it ) | The URL of the API call is the first argument. It is recommended to enclose the API call with the character ' to avoid replacing the argument ( unless you need to replace parts of it ) | ||
< | <pre>curl --silent -k -u USER:PASSWORD 'https://allegro-mm-XXXX/...'</pre> | ||
Please note that you might need to use <code>curl.exe</code> in windows. | Please note that you might need to use <code>curl.exe</code> in windows. | ||
| Line 47: | Line 46: | ||
To set the user name for basic authorization, use the '''-Headers''' parameter: | To set the user name for basic authorization, use the '''-Headers''' parameter: | ||
< | <pre>-Headers @{Authorization = ("Basic {0}" -f [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes(("{0}:{1}" -f 'USER', 'PASSWORD'))))}</pre> | ||
You also need to announce that you accept JSON as response with: | You also need to announce that you accept JSON as response with: | ||
< | <pre>-ContentType'application/json; charset=utf-8'</pre> | ||
To disable the certificate check, use: | To disable the certificate check, use: | ||
< | <pre>-SkipCertificateCheck</pre> | ||
The URL must be passed with the parameter '''-Uri''', so the full command is: | The URL must be passed with the parameter '''-Uri''', so the full command is: | ||
< | <pre>Invoke-RestMethod -Uri 'https://allegro-mm-XXXX/...' -Headers @{Authorization = ("Basic {0}" -f [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes(("{0}:{1}" -f 'USER', 'PASSWORD'))))} -ContentType'application/json; charset=utf-8' -Method 'Get' -SkipCertificateCheck</pre> | ||
=== jq === | === jq === | ||
jq ( [https://stedolan.github.io/jq/] ) is a powerful tool to extract parameters from a json document. If called without parameters, jq formats the JSON output into a readable format with indenting and new lines. It also allows to select specific values and do basic operations like addition with this values. | jq ([https://stedolan.github.io/jq/]) is a powerful tool to extract parameters from a json document. If called without parameters, jq formats the JSON output into a readable format with indenting and new lines. It also allows to select specific values and do basic operations like addition with this values. | ||
Please read the jq documentation for more information. | Please read the jq documentation for more information. | ||
| Line 237: | Line 236: | ||
This example shows IP address with the highest amount of traffic | This example shows IP address with the highest amount of traffic | ||
< | <pre>curl --silent -k -u USER:PASSWORD 'https://allegro-mm/API/stats/modules/ip/ips_paged?sort=bps&reverse=true&page=0&count=1' | jq .displayedItems[0].ip</pre> | ||
This exampe shows up to 9999 peers of a specific IP address: | This exampe shows up to 9999 peers of a specific IP address: | ||
< | <pre>curl --silent -k -u USER:PASSWORD 'https://allegro-mm/API/stats/modules/ip/ips/10.1.2.3/peers?sort=bytes&reverse=true&page=0&count=9999×pan=60&values=100' | jq '.displayedItems[].ip'</pre> | ||
=== Pcap extraction === | === Pcap extraction === | ||
| Line 247: | Line 246: | ||
The Allegro Network Multimeter allows to extract the raw packets with the REST API with the special capture URI <code>/API/data/modules/capture</code> | The Allegro Network Multimeter allows to extract the raw packets with the REST API with the special capture URI <code>/API/data/modules/capture</code> | ||
< | <pre>curl -k -u USER:PASSWORD 'https://allegro-mm/API/data/modules/capture?expression=ip==10.1.2.3' > path_to/capture.pcap</pre> | ||
The available parameters are: | The available parameters are: | ||
| Line 261: | Line 260: | ||
Example to capture everything from now on: | Example to capture everything from now on: | ||
< | <pre>curl -k -u USER:PASSWORD 'https://allegro-mm/API/data/modules/capture' > path_to/capture.pcap</pre> | ||
Example to capture a specific IP of the last hour | Example to capture a specific IP of the last hour | ||
< | <pre>curl -k -u USER:PASSWORD "https://allegro-mm/API/data/modules/capture?expression=ip==10.1.2.3&starttime=$(($(date --date="1 hour ago" +%s%N)/1000))&endtime=$(($(date +%s%N)/1000))&fromCaptureBuffer=true" > path_to/capture.pcap</pre> | ||
Example to capture a specific IP of the last hour of the first parallel Pcap analysis slot | Example to capture a specific IP of the last hour of the first parallel Pcap analysis slot | ||
< | <pre>curl -k -u USER:PASSWORD "https://allegro-mm/API/data/modules/capture?expression=ip==10.1.2.3&starttime=$(($(date --date="1 hour ago" +%s%N)/1000))&endtime=$(($(date +%s%N)/1000))&fromCaptureBuffer=true&mm-id=:1" > path_to/capture.pcap</pre> | ||
=== Virtual Link Groups === | === Virtual Link Groups === | ||
| Line 297: | Line 296: | ||
Extract the packets per second statistic of the MAC broadcast address | Extract the packets per second statistic of the MAC broadcast address | ||
< | <pre>curl --silent -k -u USER:PASSWORD 'https://allegro-mm/API/stats/modules/mac/macs/ff:ff:ff:ff:ff:ff'</pre> | ||
==== IP statistics ==== | ==== IP statistics ==== | ||
< | <pre>curl --silent -k -u USER:PASSWORD 'https://allegro-mm/API/stats/modules/ip/ips/10.1.2.3'</pre> | ||
==== Pretty displaying JSON output with jq ==== | ==== Pretty displaying JSON output with jq ==== | ||
< | <pre>curl --silent -k -u USER:PASSWORD 'https://allegro-mm-XXXX/API/stats/modules/ip/ips/10.1.2.3' | jq</pre> | ||
==== Capture a specific IP ==== | ==== Capture a specific IP ==== | ||
< | <pre>curl -k -u USER:PASSWORD 'https://allegro-mm-XXXX/API/data/modules/capture?expression=ip==10.1.2.3' > path_to/capture.pcap</pre> | ||
==== Capture two IP addresses with ports on a specific Layer 4 protocol ==== | ==== Capture two IP addresses with ports on a specific Layer 4 protocol ==== | ||
< | <pre>curl -k -u USER:PASSWORD 'https://allegro-mm-XXXX/API/data/modules/capture?expression=IP==10.1.2.3:62887 and IP==10.1.2.100:548 and l4Protocol==TCP' > path_to/capture.pcap</pre> | ||