A comprehensive adversarial testing framework for SIGTRAN protocols (M2UA, M2PA, M3UA) based on RFC 3331, RFC 4165, RFC 4666, and RFC 3788 specifications.
This tool is designed as an RFC compliance testing utility for researchers and network engineers evaluating SIGTRAN protocol implementations. While it includes tests for security-related protocol behaviors, it is primarily intended to assist in compliance verification and protocol analysis rather than security auditing or penetration testing activities.
Caveat: This is an RFC compliance testing tool. It may assist security researchers in evaluating SIGTRAN implementations, but security assessment is not its primary purpose, and it is not intended for use in penetration testing activities.
This framework provides automated adversarial testing capabilities to identify vulnerabilities and protocol violations in SIGTRAN implementations. It includes tests for:
- Common message header validation (RFC 3331/4165/4666 Section 3.1)
- M2UA protocol messages (RFC 3331 Section 3.3)
- M2PA protocol messages (RFC 4165 Section 2.3)
- M3UA protocol messages (RFC 4666 Section 3.3)
- SS7 Signalling Network Management (SSNM) messages (RFC 4666 Section 3.4)
- Routing Key Management (RKM) messages (RFC 4666 Section 3.6)
- ASP State Maintenance (ASPM) messages (RFC 4666 Section 3.5)
- ASP Traffic Maintenance (ASPTM) messages (RFC 4666 Section 3.7)
- TLV parameter validation (RFC 3331/4666 Section 3.2)
- ASP/AS state machine transitions (RFC 4666 Section 4.3)
- Timer-related behavior (RFC 4165/4666)
- Security considerations (RFC 3788)
- Comprehensive Test Coverage: 227 test cases covering all major SIGTRAN protocols
- Multi-Protocol Support: M2UA, M2PA, M3UA protocols
- Security Vulnerability Testing: Tests for SIGTRAN security attacks from RFC 3788
- Configurable Testing: YAML configuration for complex test scenarios
- Multiple Output Formats: JSON and YAML report generation
- Detailed Reporting: Pass/fail status with expected vs actual behavior
- Selective Test Execution: Run specific tests or categories
- Compliance Metrics: Severity-weighted scoring system
pip install -e .Or with development dependencies:
pip install -e ".[dev]"sigtran-test 127.0.0.1sigtran-test 127.0.0.1 --port 2905sigtran-test 127.0.0.1 --verbosesigtran-test --config config.yaml| Option | Description |
|---|---|
target_host |
Target host IP address (required) |
--port |
Target port (default: 2905) |
--protocol |
Protocol to use: sctp or tcp (default: sctp) |
--timeout |
Connection timeout in seconds (default: 5.0) |
--verbose, -v |
Verbose output |
Example config.yaml:
target_host: "127.0.0.1"
target_port: 2905
protocol: "sctp"
timeout: 5.0
test_categories:
- common_header
- m2ua_message
- m2pa_message
- m3ua_message
- aspm
- asptm
- parameter
- state
- timing
- security
interface_id: 1
routing_context: 1
delay_between_tests: 0.1
retry_count: 3
output_format: "text"
output_file: null
verbose: false
debug: falseTests for SIGTRAN common message header validation (RFC 3331/4666 Section 3.1):
- Invalid protocol version
- Unsupported message class
- Invalid message type
- Message length too short/zero
- Truncated header
- Extra data after message
- Reserved field non-zero
Tests for M2UA protocol messages (RFC 3331 Section 3.3):
- DATA message without Interface Identifier
- Invalid Interface Identifier format
- State Request invalid state
- Protocol Data too long
- Invalid Traffic Mode Type
- Unexpected message sequence
- Duplicate ASP Up
Tests for M2PA protocol messages (RFC 4165 Section 2.3):
- Invalid Link Status value
- User Data before alignment
- Invalid Stream Identifier
- Invalid FSN value
- Out of sequence FSN
- Missing alignment sequence
- BSN/FSN wrap around
Tests for M3UA protocol messages (RFC 4666 Section 3.3):
- DATA without Protocol Data
- Invalid Routing Context
- Invalid Network Appearance
- ASP Active without Routing Context
- Invalid Traffic Mode
- DATA before ASP Active
- MTP3 restart scenarios
- Error handling for all error codes
Tests for ASP State Maintenance messages (RFC 4666 Section 3.5):
- ASP Up with invalid version
- ASP Down when already down
- Heartbeat before ASP Up
- Invalid Heartbeat format
- ASP Up Ack before ASP Up
Tests for ASP Traffic Maintenance messages (RFC 4666 Section 3.7):
- ASP Active without ASP Up
- ASP Active with invalid Traffic Mode
- ASP Active with multiple Routing Contexts
- ASP Inactive without ASP Active
- ASP Active Ack before ASP Active
Tests for SS7 Signalling Network Management messages (RFC 4666 Section 3.4):
- DUNA invalid DPC format
- DAVA invalid APC
- SCON invalid congestion level
- DUPU invalid cause
- DRST restricted DPC
- DAUD unsolicited audit
- SSNM on wrong stream
Tests for TLV parameter validation (RFC 3331/4666 Section 3.2):
- Missing mandatory parameter
- Invalid parameter tag
- Parameter length mismatch
- Duplicate parameter
- Parameter padding error
- Unexpected parameter
- Zero length parameter
- Invalid info string encoding
Tests for ASP/AS state machine transitions (RFC 4666 Section 4.3):
- Invalid ASP state transition
- ASP Active timeout
- Multiple ASP Active for Override mode
- AS state inconsistency
- Recovery after failure
- ASP failover/failback
- Loadshare/broadcast mode
Tests for timer-related behavior (RFC 4165/4666):
- Heartbeat timer expiry
- Heartbeat rate too fast
- ASP Active Ack timeout
- Link Alignment timer expiry
- Proving period too short
Tests for security-related vulnerabilities (RFC 3788):
- Message flooding
- Invalid ASP Identifier
- Interface ID spoofing
- Routing Context manipulation
- Replay attacks
- Connection flooding
- Malformed TLV parameters
- Amplification attacks
- State confusion attacks
from sigtran_test_framework import (
SIGTRANTestFramework,
TestRunner,
get_all_test_cases,
)
# Create framework instance
framework = SIGTRANTestFramework(
target_host="127.0.0.1",
target_port=2905,
protocol="sctp",
timeout=5.0,
)
# Get all test cases
test_cases = get_all_test_cases()
print(f"Total test cases: {len(test_cases)}")
# Run tests using runner
runner = TestRunner(
target_host="127.0.0.1",
target_port=2905,
protocol="sctp",
timeout=5.0,
verbose=True,
)
results = runner.run_all_tests()
print(runner.generate_report())from sigtran_test_framework.tests import CommonHeaderTests
framework = SIGTRANTestFramework(target_host="127.0.0.1")
result = CommonHeaderTests.test_invalid_version(framework)
print(f"Test passed: {result.passed}")Each test returns a TestResult with:
@dataclass
class TestResult:
test_id: str # Unique test identifier (e.g., "CH-001")
test_name: str # Human-readable test name
category: TestCategory # Test category enum
passed: bool # Whether the test passed
expected_behavior: str # What RFC says should happen
actual_behavior: str # What actually happened
details: dict # Additional test details
error_code: int # Error code if applicableThe framework provides severity-weighted compliance scoring:
| Grade | Score Threshold |
|---|---|
| A | 95%+ |
| B | 85%+ |
| C | 70%+ |
| D | 50%+ |
| F | Below 50% |
Severity levels:
- CRITICAL: Common header validation, security issues
- HIGH: Message type/class validation, parameter issues
- MEDIUM: State machine, timing issues
- LOW: Informational tests
- INFO: Baseline functionality
- RFC 3331 - SS7 MTP2 User Adaptation Layer (M2UA)
- RFC 4165 - SS7 MTP2-User Peer-to-Peer Adaptation Layer (M2PA)
- RFC 4666 - SS7 MTP3-User Adaptation Layer (M3UA)
- RFC 3788 - Security Considerations for SIGTRAN
| Protocol | Default Port |
|---|---|
| M2UA | 2904 |
| M2PA | 2905 |
| M3UA | 2905 |
# Run all unit tests
pytest tests/unit/
# Run specific test file
pytest tests/unit/test_constants.py
# Run with coverage
pytest --cov=sigtran_test_framework tests/# Format code
black src/
# Lint code
ruff check src/The easiest way to test this framework is using OsmoSTP from the Osmocom project:
# Start OsmoSTP emulator
docker-compose up -d
# Check logs
docker logs -f sigtran-test-stp
# Connect to VTY interface
telnet localhost 4239-
Install OsmoSTP:
# Debian/Ubuntu apt-get install osmo-stp # Or build from source git clone https://gitea.osmocom.org/osmo-ttcn3-hacks.git
-
Configure OsmoSTP for SIGTRAN:
# Edit /etc/osmo-stp.cfg or use the provided config # Enable SCTP on ports 2904 (M2UA), 2905 (M2PA/M3UA) # Start OsmoSTP osmo-stp -c /path/to/config.cfg
-
Run tests:
sigtran-test 127.0.0.1 --port 2905 --verbose
-
Eclipse Titan TTCN-3: Protocol emulation for M3UA testing (commercial license required for high throughput)
-
Osmocom docker-playground: Complete test environment with Sigtran support
The unit tests (pytest tests/unit/) can run without any external server. For integration testing:
- Use Wireshark to capture SCTP traffic
- Send malformed packets to observe implementation responses
- Test against any M2UA/M2PA/M3UA-enabled device (SS7 gateway, telecom equipment)
MIT License
Contributions are welcome. Please ensure:
- All tests pass (
pytest tests/unit/) - Code follows existing style conventions
- New tests include RFC section references
- Documentation is updated for new features