Skip to content

ANTA catalog for STUN tests

Tests

Test functions related to various STUN settings.

VerifyStunClient

Static Badge Static Badge
Replaced with: VerifyStunClientTranslation

(Deprecated) Verifies the translation for a source address on a STUN client.

Alias for the VerifyStunClientTranslation test to maintain backward compatibility. When initialized, it will emit a deprecation warning and call the VerifyStunClientTranslation test.

Examples 
anta.tests.stun:
  - VerifyStunClient:
      stun_clients:
        - source_address: 172.18.3.2
          public_address: 172.18.3.21
          source_port: 4500
          public_port: 6006

VerifyStunClientTranslation

Verifies the translation for a source address on a STUN client.

This test performs the following checks for each specified address family:

  1. Validates that there is a translation for the source address on the STUN client.
  2. If public IP and port details are provided, validates their correctness against the configuration.
Expected Results
  • Success: If all of the following conditions are met:
    • The test will pass if the source address translation is present.
    • If public IP and port details are provided, they must also match the translation information.
  • Failure: If any of the following occur:
    • There is no translation for the source address on the STUN client.
    • The public IP or port details, if specified, are incorrect.
Examples 
anta.tests.stun:
  - VerifyStunClientTranslation:
      stun_clients:
        - source_address: 172.18.3.2
          public_address: 172.18.3.21
          source_port: 4500
          public_port: 6006
        - source_address: 100.64.3.2
          public_address: 100.64.3.21
          source_port: 4500
          public_port: 6006

Inputs

Name Type Description Default
stun_clients list[StunClientTranslation]
List of STUN clients.
-
Source code in anta/tests/stun.py 
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
class VerifyStunClientTranslation(AntaTest):
    """Verifies the translation for a source address on a STUN client.

    This test performs the following checks for each specified address family:

      1. Validates that there is a translation for the source address on the STUN client.
      2. If public IP and port details are provided, validates their correctness against the configuration.

    Expected Results
    ----------------
    * Success: If all of the following conditions are met:
        - The test will pass if the source address translation is present.
        - If public IP and port details are provided, they must also match the translation information.
    * Failure: If any of the following occur:
        - There is no translation for the source address on the STUN client.
        - The public IP or port details, if specified, are incorrect.

    Examples
    --------
    ```yaml
    anta.tests.stun:
      - VerifyStunClientTranslation:
          stun_clients:
            - source_address: 172.18.3.2
              public_address: 172.18.3.21
              source_port: 4500
              public_port: 6006
            - source_address: 100.64.3.2
              public_address: 100.64.3.21
              source_port: 4500
              public_port: 6006
    ```
    """

    categories: ClassVar[list[str]] = ["stun"]
    commands: ClassVar[list[AntaCommand | AntaTemplate]] = [AntaTemplate(template="show stun client translations {source_address} {source_port}", revision=1)]

    class Input(AntaTest.Input):
        """Input model for the VerifyStunClientTranslation test."""

        stun_clients: list[StunClientTranslation]
        """List of STUN clients."""
        StunClientTranslation: ClassVar[type[StunClientTranslation]] = StunClientTranslation

    def render(self, template: AntaTemplate) -> list[AntaCommand]:
        """Render the template for each STUN translation."""
        return [template.render(source_address=client.source_address, source_port=client.source_port) for client in self.inputs.stun_clients]

    @AntaTest.anta_test
    def test(self) -> None:
        """Main test function for VerifyStunClientTranslation."""
        self.result.is_success()

        # Iterate over each command output and corresponding client input
        for command, client_input in zip(self.instance_commands, self.inputs.stun_clients):
            bindings = command.json_output["bindings"]
            input_public_address = client_input.public_address
            input_public_port = client_input.public_port

            # If no bindings are found for the STUN client, mark the test as a failure and continue with the next client
            if not bindings:
                self.result.is_failure(f"{client_input} - STUN client translation not found")
                continue

            # Extract the transaction ID from the bindings
            transaction_id = next(iter(bindings.keys()))

            # Verifying the public address if provided
            if input_public_address and str(input_public_address) != (actual_public_address := get_value(bindings, f"{transaction_id}.publicAddress.ip")):
                self.result.is_failure(f"{client_input} - Incorrect public-facing address - Expected: {input_public_address} Actual: {actual_public_address}")

            # Verifying the public port if provided
            if input_public_port and input_public_port != (actual_public_port := get_value(bindings, f"{transaction_id}.publicAddress.port")):
                self.result.is_failure(f"{client_input} - Incorrect public-facing port - Expected: {input_public_port} Actual: {actual_public_port}")

VerifyStunServer

Verifies the STUN server status is enabled and running.

Expected Results
  • Success: The test will pass if the STUN server status is enabled and running.
  • Failure: The test will fail if the STUN server is disabled or not running.
Examples 
anta.tests.stun:
  - VerifyStunServer:
Source code in anta/tests/stun.py 
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
class VerifyStunServer(AntaTest):
    """Verifies the STUN server status is enabled and running.

    Expected Results
    ----------------
    * Success: The test will pass if the STUN server status is enabled and running.
    * Failure: The test will fail if the STUN server is disabled or not running.

    Examples
    --------
    ```yaml
    anta.tests.stun:
      - VerifyStunServer:
    ```
    """

    categories: ClassVar[list[str]] = ["stun"]
    commands: ClassVar[list[AntaCommand | AntaTemplate]] = [AntaCommand(command="show stun server status", revision=1)]

    @AntaTest.anta_test
    def test(self) -> None:
        """Main test function for VerifyStunServer."""
        command_output = self.instance_commands[0].json_output
        status_disabled = not command_output.get("enabled")
        not_running = command_output.get("pid") == 0

        if status_disabled and not_running:
            self.result.is_failure("STUN server status is disabled and not running")
        elif status_disabled:
            self.result.is_failure("STUN server status is disabled")
        elif not_running:
            self.result.is_failure("STUN server is not running")
        else:
            self.result.is_success()

Input models

Module containing input models for services tests.

StunClientTranslation

STUN (Session Traversal Utilities for NAT) model represents the configuration of an IPv4-based client translations.

Name Type Description Default
source_address IPv4Address
The IPv4 address of the STUN client
-
source_port Port
The port number used by the STUN client for communication. Defaults to 4500.
4500
public_address IPv4Address | None
The public-facing IPv4 address of the STUN client, discovered via the STUN server.
None
public_port Port | None
The public-facing port number of the STUN client, discovered via the STUN server.
None
Source code in anta/input_models/stun.py 
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
class StunClientTranslation(BaseModel):
    """STUN (Session Traversal Utilities for NAT) model represents the configuration of an IPv4-based client translations."""

    model_config = ConfigDict(extra="forbid")
    source_address: IPv4Address
    """The IPv4 address of the STUN client"""
    source_port: Port = 4500
    """The port number used by the STUN client for communication. Defaults to 4500."""
    public_address: IPv4Address | None = None
    """The public-facing IPv4 address of the STUN client, discovered via the STUN server."""
    public_port: Port | None = None
    """The public-facing port number of the STUN client, discovered via the STUN server."""

    def __str__(self) -> str:
        """Return a human-readable string representation of the StunClientTranslation for reporting.

        Examples
        --------
        Client 10.0.0.1 Port: 4500
        """
        return f"Client {self.source_address} Port: {self.source_port}"