Feat/improve traceroute

.github/workflows/ci.yml

@@ -2,7 +2,6 @@ name: Continuous Integration
 
 on:
   push:
-  pull_request:
 
 permissions:
   contents: write

.github/workflows/e2e_checks.yml

@@ -0,0 +1,55 @@
+name: E2E - Test checks
+
+on:
+  push:
+
+permissions:
+  contents: read
+
+jobs:
+  test_e2e:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: |
+          sudo add-apt-repository ppa:katharaframework/kathara
+          sudo apt-get update
+          sudo apt-get install -y jq kathara
+      - name: Setup kathara
+        run: |
+          echo '{
+          "image": "kathara/base",
+          "manager_type": "docker",
+          "terminal": "/usr/bin/xterm",
+          "open_terminals": false,
+          "device_shell": "/bin/bash",
+          "net_prefix": "kathara",
+          "device_prefix": "kathara",
+          "debug_level": "INFO",
+          "print_startup_log": true,
+          "enable_ipv6": false,
+          "last_checked": 1721834897.2415252,
+          "hosthome_mount": false,
+          "shared_mount": true,
+          "image_update_policy": "Prompt",
+          "shared_cds": 1,
+          "remote_url": null,
+          "cert_path": null,
+          "network_plugin": "kathara/katharanp_vde"
+          }' > ~/.config/kathara.conf
+
+      - name: Build binary for e2e
+        uses: goreleaser/goreleaser-action@v5
+        with:
+          version: latest
+          args: build --single-target --clean  --snapshot --config .goreleaser-ci.yaml
+
+      - name: Run e2e tests
+        run: |
+          ./scripts/run_e2e_tests.sh

.github/workflows/end2end.yml

@@ -4,7 +4,6 @@
 name: End2End Testing
 on:
   push:
-  pull_request:
 
 jobs:
   end2end:

.github/workflows/pre-commit.yml

@@ -1,6 +1,7 @@
 name: pre-commit.ci
 
-on: [push, pull_request]
+on:
+  push:
 
 jobs:
   pre-commit:

.github/workflows/test_sast.yml

@@ -2,7 +2,6 @@ name: Test - SAST
 
 on:
   push:
-  pull_request:
 
 permissions:
   contents: read
@@ -21,4 +20,4 @@ jobs:
       - name: Run Gosec Security Scanner
         uses: securego/gosec@master
         with:
-          args: ./...
+          args: ./...

.github/workflows/test_unit.yml

@@ -2,7 +2,6 @@ name: Test - Unit
 
 on:
   push:
-  pull_request:
 
 permissions:
   contents: read

.gitignore

@@ -29,3 +29,4 @@ gen
 
 # Temporary directory
 .tmp/*
+dist

README.md

@@ -33,7 +33,9 @@
     - [DNS Metrics](#dns-metrics)
   - [Check: Traceroute](#check-traceroute)
     - [Example configuration](#example-configuration-3)
-    - [Required Capabilities](#required-capabilities)
+    - [Optional Capabilities](#optional-capabilities)
+    - [Traceroute Prometheus Metrics](#traceroute-prometheus-metrics)
+    - [Traceroute API Metrics](#traceroute-api-metrics)
 - [API](#api)
 - [Metrics](#metrics)
 - [Code of Conduct](#code-of-conduct)
@@ -409,7 +411,7 @@ latency:
 
 - `sparrow_latency_duration_seconds`
   - Type: Gauge
-  - Description: Latency with status information of targets. This metric is DEPRECATED. Use `sparrow_latency_seconds`. 
+  - Description: Latency with status information of targets. This metric is DEPRECATED. Use `sparrow_latency_seconds`.
   - Labelled with `target` and `status`
 
 - `sparrow_latency_seconds`
@@ -483,7 +485,8 @@ dns:
 | ---------------- | ----------------- | ---------------------------------------------------------------------------- |
 | `interval`       | `duration`        | Interval to perform the Traceroute check.                                    |
 | `timeout`        | `duration`        | Timeout for every hop.                                                       |
-| `retries`        | `integer`         | Number of times to retry the traceroute for a target, if it fails.           |
+| `retry.count`    | `integer`         | Number of retries for the latency check.                                                                                                                     |
+| `retry.delay`    | `duration`        | Initial delay between retries for the latency check.                                                                                                         |
 | `maxHops`        | `integer`         | Maximum number of hops to try before giving up.                              |
 | `targets`        | `list of objects` | List of targets to traceroute to.                                            |
 | `targets[].addr` | `string`          | The address of the target to traceroute to. Can be an IP address or DNS name |
@@ -494,25 +497,100 @@ dns:
 <!-- markdownlint-enable MD024 -->
 
 ```yaml
- traceroute:
+traceroute:
   interval: 5s
   timeout: 3s
-  retries: 3
-  maxHops: 8
+  retry:
+    count: 3
+    delay: 1s
+  maxHops: 30
   targets:
     - addr: 8.8.8.8
       port: 53
     - addr: www.google.com
       port: 80
 ```
 
-#### Required Capabilities
+#### Optional Capabilities
+
+Sparrow does not need any extra permissions to run this check. However, some data, like the ip address
+of the hop that dropped a packet, will not be available. To enable this functionality, there are two options:
+
+- Run sparrow as root:
+
+  ```bash
+  sudo sparrow run --config config.yaml
+  ```
+
+- Allow sparrow to create raw sockets, by assigning the `CAP_NET_RAW` capability to the sparrow binary:
+
+  ```bash
+  sudo setcap 'cap_net_raw=ep' sparrow
+  ```
+
+#### Traceroute Prometheus Metrics
+
+- `sparrow_traceroute_check_duration_ms{target="google.com"} 43150`
+  - Type: Gauge
+  - Description: How long the last traceroute took for this target in total
+- `sparrow_traceroute_minimum_hops{target="google.com"} 14`
+  - Type: Gauge
+  - Description: The minimum number of hops required to reach a target
+
+#### Traceroute API Metrics
 
-To use this check, sparrow needs to be run with the `CAP_NET_RAW` capability or elevated privileges to be able to send raw packets.
-Using the `CAP_NET_RAW` capability is recommended over running sparrow as sudo.
+The traceroute check exposes additional data through its rest API that isn't available in prometheus.
+This data give a more detailed breakdown of the trace and can be found at `/v1/metrics/traceroute` and is
+meant to be a json representation of traditional traceroute output:
 
 ```bash
-sudo setcap 'cap_net_raw=ep' sparrow
+$ traceroute -T -q 1 100.1.2.2
+ 1  200.2.0.1 (200.2.0.1)  2 ms
+ 2  11.0.0.34 (11.0.0.34)  5 ms
+ ...
+```
+
+Is roughly equal to this:
+
+```json
+{
+  "data": {
+    "100.1.2.2": {
+      "MinHops": 1,
+      "Hops": {
+        "1": [
+          {
+            "Latency": 2,
+            "Addr": {
+              "IP": "200.2.0.1",
+              "Port": 80,
+              "Zone": ""
+            },
+            "Name": "",
+            "Ttl": 1,
+            "Reached": false
+          }
+        ],
+        "2": [
+          {
+            "Latency": 5,
+            "Addr": {
+              "IP": "11.0.0.34",
+              "Port": 80,
+              "Zone": ""
+            },
+            "Name": "",
+            "Ttl": 2,
+            "Reached": false
+          }
+        ]
+        ...
+      }
+    },
+  },
+  "timestamp": "2024-07-26T15:49:39.60760766+02:00"
+}
+
 ```
 
 ## API

e2e/traceroute/lab.conf

@@ -0,0 +1,21 @@
+LAB_DESCRIPTION="A simple example showing how to configure static routes"
+LAB_VERSION=2.0
+LAB_AUTHOR="T. Caiazzi, G. Di Battista, M. Patrignani, M. Pizzonia, F. Ricci, M. Rimondini"
+[email protected]
+LAB_WEB=http://www.kathara.org/
+
+r1[0]="A"
+r1[1]="B"
+r1[image]="kathara/base"
+
+r2[0]="C"
+r2[1]="B"
+r2[image]="kathara/base"
+
+pc1[0]="A"
+pc1[image]="kathara/base"
+pc1[env]="LOG_LEVEL=DEBUG"
+pc1[env]="LOG_FORMAT=TEXT"
+
+pc2[0]="C"
+pc2[image]="kathara/base"

e2e/traceroute/pc1.startup

@@ -0,0 +1,2 @@
+ip address add 195.11.14.5/24 dev eth0
+ip route add default via 195.11.14.1 dev eth0

e2e/traceroute/pc2.startup

@@ -0,0 +1,3 @@
+ip address add 200.1.1.7/24 dev eth0
+ip route add default via 200.1.1.1 dev eth0
+systemctl start apache2

e2e/traceroute/r1.startup

@@ -0,0 +1,3 @@
+ip address add 195.11.14.1/24 dev eth0
+ip address add 100.0.0.9/30 dev eth1
+ip route add 200.1.1.0/24 via 100.0.0.10 dev eth1

e2e/traceroute/r2.startup

@@ -0,0 +1,3 @@
+ip address add 200.1.1.1/24 dev eth0
+ip address add 100.0.0.10/30 dev eth1
+ip route add 195.11.14.0/24 via 100.0.0.9 dev eth1

e2e/traceroute/shared/config.yaml

@@ -0,0 +1,25 @@
+# DNS sparrow is exposed on
+name: sparrow.caas-t21.telekom.de
+
+# Selects and configures a loader to continuously fetch the checks' configuration at runtime
+loader:
+  # Defines which loader to use. Options: "file | http"
+  type: file
+  # The interval in which sparrow tries to fetch a new configuration
+  # If this isn't set or set to 0, the loader will only retrieve the configuration once
+  interval: 30s
+
+  # Config specific to the file loader
+  # The file loader is not intended for production use
+  file:
+    # Location of the file in the local filesystem
+    path: /shared/config.yaml
+
+traceroute:
+  interval: 5s
+  timeout: 3s
+  retries: 3
+  maxHops: 3
+  targets:
+    - addr: 200.1.1.7
+      port: 80

e2e/traceroute/shared/get_api.sh

@@ -0,0 +1,2 @@
+curl -s localhost:8080/v1/metrics/traceroute > /shared/api.json
+curl -s localhost:8080/metrics > /shared/prometheus.txt

e2e/traceroute/test.sh

@@ -0,0 +1,74 @@
+#!/bin/bash
+
+EXIT_CODE=0
+
+function cleanup()
+{
+    kathara lclean
+    yes | rm ./shared/api.json ./shared/prometheus.txt ./shared/sparrow
+    exit $EXIT_CODE
+}
+
+function error() {
+    echo "[ ERROR ]: $@"
+    EXIT_CODE=1
+}
+
+function info() {
+    echo "[ INFO ]: $@"
+}
+
+function success() {
+    echo "[ SUCCESS ]: $@"
+}
+
+function check_prometheus_output() {
+  if grep -q 'sparrow_traceroute_minimum_hops{target="200.1.1.7"} 3' ./shared/prometheus.txt; then
+    success "The specific Prometheus output is present."
+  else
+    error "The specific Prometheus output is not present."
+  fi
+}
+
+function check_api_output() {
+    if jq -e '
+        .data["200.1.1.7"].hops | 
+        .["1"][0].addr.ip == "195.11.14.1" and 
+        .["1"][0].reached == false and
+        .["1"][0].ttl == 1 and
+        .["2"][0].addr.ip == "100.0.0.10" and 
+        .["2"][0].reached == false and
+        .["2"][0].ttl == 2 and
+        .["3"][0].addr.ip == "200.1.1.7" and 
+        .["3"][0].reached == true and
+        .["3"][0].ttl == 3 and
+        .["3"][0].addr.port == 80' ./shared/api.json > /dev/null; then
+        success "The API output matches the expected hops and conditions."
+    else
+        error "The API output does not match the expected hops and conditions."
+        cat ./shared/api.json
+    fi
+}
+
+trap cleanup EXIT
+
+# Start the Kathará lab
+kathara lstart
+
+
+# Copy the binary into the shared folder
+info "Using $SPARROW_BIN"
+cp $SPARROW_BIN ./shared/sparrow
+
+# Start Sparrow on pc1
+kathara exec pc1 "/shared/sparrow run --config /shared/config.yaml" &
+
+# Wait for 10 seconds to ensure Sparrow is up and running
+sleep 10
+
+# Curl the API of Sparrow
+kathara exec pc1 "bash /shared/get_api.sh"
+
+check_prometheus_output
+
+check_api_output