Test Plan for Paramiko SSH Library

Testing Strategy Overview

This test plan covers the Paramiko SSH2 protocol library, a mature Python implementation of SSH client/server functionality. The strategy focuses on:

1. Security-Critical Components: Authentication, key management, encryption, and protocol handling

2. Core Protocol Logic: SSH transport, channel management, packet handling

3. File Transfer: SFTP client/server operations

4. Configuration Parsing: SSH config file handling with complex matching rules

5. Cross-Platform Compatibility: Windows-specific components and Unix socket handling

6. Integration Points: Agent forwarding, proxy commands, GSSAPI authentication

Test Framework Recommendation

Primary Framework: pytest with pytest-relaxed (already in use)

Supporting Tools:

• pytest-xdist for parallel test execution (already configured)
• unittest.mock for mocking external dependencies
• coverage for code coverage tracking (already configured, target <7)
• Custom fixtures in tests/conftest.py for common test infrastructure

Rationale: The repository already uses pytest extensively with 50+ test files. Continue this pattern for consistency.

Coverage Targets

• Overall Target: 85%+ line coverage
• Critical Security Modules: 95%+ coverage
• auth_handler.py, auth_strategy.py
• pkey.py, rsakey.py, ecdsakey.py, ed25519key.py
• transport.py, packet.py
• Business Logic: 90%+ coverage
• client.py, server.py
• sftp_client.py, sftp_server.py
• config.py
• Utility Modules: 80%+ coverage
• util.py, common.py, message.py

Module-by-Module Test Priorities

1. Authentication & Key Management (CRITICAL)

`paramiko/auth_handler.py` (42.0KB)

Priority: CRITICAL - Handles all authentication mechanisms

Must Test:

• All authentication methods: password, publickey, keyboard-interactive, GSSAPI
• Authentication state machine transitions
• Multi-factor authentication flows
• Authentication failure handling and retry logic
• Partial authentication success scenarios

Complex Branches:

• _parse_userauth_request() - multiple auth type branches
• _parse_userauth_success() - state validation
• _parse_userauth_failure() - retry logic with allowed methods
• _parse_userauth_banner() - banner handling during auth

Edge Cases:

• Invalid authentication sequences
• Malformed authentication messages
• Authentication timeout scenarios
• Concurrent authentication attempts
• Server rejecting all auth methods

`paramiko/auth_strategy.py` (11.2KB)

Priority: CRITICAL - Modern authentication strategy pattern

Must Test:

• AuthStrategy.authenticate() - source iteration and fallback
• Password.authenticate() - lazy password retrieval
• PrivateKey.authenticate() - key loading and signing
• InMemoryPrivateKey vs OnDiskPrivateKey - different key sources
• NoneAuth.authenticate() - none authentication method

Edge Cases:

• Password getter raising exceptions
• Private key file not found or corrupted
• Private key requiring passphrase when none provided
• All auth sources failing
• Partial success requiring additional auth

`paramiko/pkey.py` (35.9KB)

Priority: CRITICAL - Base key handling with multiple formats

Must Test:

• PKey.from_path() - loading keys from filesystem
• PKey.from_type_string() - parsing key type and bytes
• _read_private_key_pem() - PEM format parsing
• _read_private_key_openssh() - OpenSSH format parsing
• _write_private_key() - key serialization with/without password
• sign_ssh_data() - signature generation
• verify_ssh_sig() - signature verification
• Certificate loading via load_certificate()

Complex Branches:

• Multiple key formats (PEM, OpenSSH, encrypted, unencrypted)
• Different encryption algorithms (AES-128-CBC, AES-256-CTR, etc.)
• Key with/without certificates
• Passphrase-protected keys
• Malformed key data

Edge Cases:

• Empty key files
• Truncated key data
• Invalid base64 encoding
• Unsupported key types
• Wrong passphrase
• Corrupted key checksums
• Keys with unusual padding

`paramiko/rsakey.py`, `paramiko/ecdsakey.py`, `paramiko/ed25519key.py`

Priority: CRITICAL - Specific key type implementations

Must Test:

• Key generation for each type
• Signature generation and verification
• Key size validation
• Curve validation (ECDSA: P-256, P-384, P-521)
• Serialization/deserialization
• Interoperability with OpenSSH keys

2. Transport & Protocol (CRITICAL)

`paramiko/transport.py` (132.2KB - LARGEST FILE)

Priority: CRITICAL - Core SSH protocol implementation

Must Test:

• Connection establishment and handshake
• Key exchange algorithms (all supported KEX methods)
• Encryption/MAC algorithm negotiation
• Rekeying logic and triggers
• Channel multiplexing
• Global request handling
• Keep-alive mechanism
• Connection shutdown (clean and abrupt)

Complex Branches:

• _check_banner() - protocol version negotiation
• _send_kex_init() - algorithm negotiation
• _parse_kex_init() - peer algorithm selection
• _parse_newkeys() - cipher activation
• run() - main event loop with multiple message types
• open_channel() - channel creation with various types
• _check_keepalive() - timeout detection

Edge Cases:

• Incompatible protocol versions
• No common algorithms
• Rekey during active transfers
• Packet corruption
• Out-of-order packets
• Connection timeout during handshake
• Simultaneous rekey from both sides
• Channel ID exhaustion

`paramiko/packet.py` (23.7KB)

Priority: CRITICAL - Low-level packet handling

Must Test:

• send_message() - packet construction with encryption/MAC
• read_message() - packet parsing and decryption
• _build_packet() - padding and encryption
• Compression (zlib) integration
• MAC computation and verification
• Sequence number handling
• Rekey triggering based on byte/packet counts

Complex Branches:

• Different cipher modes (CBC, CTR, GCM)
• ETM (Encrypt-then-MAC) vs traditional MAC
• AEAD ciphers (ChaCha20-Poly1305)
• Compressed vs uncompressed packets

Edge Cases:

• Packet size limits (min/max)
• MAC verification failures
• Sequence number wraparound
• Partial packet reads
• Socket errors during read/write
• Handshake timeout

`paramiko/channel.py` (48.1KB)

Priority: HIGH - Channel management

Must Test:

• Channel lifecycle (open, active, closed)
• Window size management and flow control
• recv() and send() operations
• exec_command(), invoke_shell(), invoke_subsystem()
• PTY allocation with get_pty()
• Environment variable setting
• Exit status handling
• stderr separation
• X11 forwarding requests
• Agent forwarding requests

Complex Branches:

• Window adjustment logic
• Blocking vs non-blocking I/O
• Combined stderr mode
• EOF handling
• Channel close sequencing

Edge Cases:

• Zero window size
• Window overflow
• Sending after EOF
• Receiving after close
• Timeout on blocked operations

3. SFTP Implementation (HIGH)

`paramiko/sftp_client.py` (35.0KB)

Priority: HIGH - Client-side SFTP operations

Must Test:

• from_transport() - SFTP session initialization
• get() and put() - file transfer with callbacks
• listdir(), listdir_attr() - directory listing
• mkdir(), rmdir(), remove() - file operations
• rename(), stat(), lstat() - metadata operations
• chmod(), chown() - permission changes
• symlink(), readlink() - symlink operations
• getcwd(), chdir() - directory navigation
• getfo(), putfo() - file-like object transfers

Complex Branches:

• Large file transfers with progress callbacks
• Concurrent file operations
• Attribute preservation during transfers
• Error recovery and retry logic

Edge Cases:

• Empty files
• Very large files (>2GB)
• Permission denied scenarios
• Non-existent paths
• Symlink loops
• Disk full conditions
• Network interruption during transfer

`paramiko/sftp_server.py` (19.0KB)

Priority: HIGH - Server-side SFTP implementation

Must Test:

• Request dispatching to SFTPServerInterface
• _process() - main request handler
• All SFTP operations (open, read, write, close, etc.)
• Error code translation
• Handle management

Edge Cases:

• Invalid handles
• Unsupported operations
• Malformed requests
• Resource exhaustion

4. Configuration Parsing (HIGH)

`paramiko/config.py` (26.7KB)

Priority: HIGH - Complex SSH config parsing

Must Test:

• parse() - config file parsing
• lookup() - hostname matching and config merging
• Host pattern matching (wildcards, negation)
• Match directive evaluation (host, user, localuser, exec)
• Token expansion (%h, %p, %r, %u, %l, %L, %C, %d, %n)
• CanonicalizeHostname logic
• ProxyCommand and ProxyJump parsing
• Multi-value keys (IdentityFile, LocalForward, RemoteForward)

Complex Branches:

• _expand_variables() - token substitution
• _expand_hostname() - hostname canonicalization
• _does_match() - Match criteria evaluation
• _pattern_matches() - glob pattern matching
• Recursive Match evaluation

Edge Cases:

• Circular hostname canonicalization
• Match exec command failures
• Invalid token syntax
• Missing required tokens
• Config file syntax errors
• Empty config files
• Very long config files
• Conflicting directives

5. Key Exchange Algorithms (MEDIUM)

`paramiko/kex_*.py` files

Priority: MEDIUM - Various KEX implementations

Must Test:

• KexGroup1, KexGroup14, KexGroup16 - DH group exchange
• KexGex - DH GEX with dynamic groups
• KexNistp256, KexNistp384, KexNistp521 - ECDH
• KexCurve25519 - Curve25519 exchange
• KexGSS* - GSSAPI key exchange

Must Test:

• start_kex() - initiation
• parse_next() - message handling
• Shared secret computation
• Hash generation for exchange hash

Edge Cases:

• Invalid peer public keys
• Out-of-range DH parameters
• Unsupported curves
• GSSAPI context failures

6. Host Key Management (MEDIUM)

`paramiko/hostkeys.py` (12.8KB)

Priority: MEDIUM - Known hosts management

Must Test:

• load() - parsing known_hosts file
• save() - writing known_hosts file
• lookup() - hostname matching (including hashed)
• check() - key verification
• add() - adding new host keys
• hash_host() - hostname hashing

Edge Cases:

• Hashed hostnames
• Hostname patterns with wildcards
• Multiple keys per host
• Invalid key formats in file
• File permission issues

7. Utility & Helper Modules (MEDIUM)

`paramiko/message.py` (9.1KB)

Priority: MEDIUM - Binary message encoding/decoding

Must Test:

• All get_*() methods (int, string, bytes, mpint, etc.)
• All add_*() methods
• rewind() - message replay
• Type validation

Edge Cases:

• Reading past end of message
• Invalid UTF-8 strings
• Negative mpints
• Very large integers

`paramiko/util.py` (9.3KB)

Priority: MEDIUM - Utility functions

Must Test:

• deflate_long(), inflate_long() - bigint conversion
• format_binary() - hex formatting
• safe_string() - string sanitization
• constant_time_bytes_eq() - timing-safe comparison
• retry_on_signal() - signal handling

`paramiko/buffered_pipe.py` (7.1KB)

Priority: MEDIUM - Buffered I/O

Must Test:

• feed() - data buffering
• read() - data consumption with timeout
• empty() - buffer clearing
• Event notification

Edge Cases:

• Buffer overflow
• Read timeout
• Concurrent feed/read
• Close during read

8. Platform-Specific Code (LOW-MEDIUM)

`paramiko/_winapi.py` (10.9KB)

Priority: MEDIUM (Windows only)

Must Test:

• MemoryMap - shared memory operations
• get_current_user() - token retrieval
• get_security_attributes_for_user() - security descriptor creation

Note: Requires Windows environment or extensive mocking

`paramiko/win_pageant.py` (4.1KB)

Priority: LOW - Pageant agent integration

Must Test:

• _query_pageant() - IPC with Pageant
• Key retrieval from Pageant

`paramiko/agent.py` (15.5KB)

Priority: MEDIUM - SSH agent integration

Must Test:

• Agent.get_keys() - key enumeration
• AgentKey.sign_ssh_data() - signing via agent
• Unix socket and Windows named pipe connections
• Agent forwarding setup

9. Server Implementation (MEDIUM)

`paramiko/server.py` (29.7KB)

Priority: MEDIUM - Server interface

Must Test:

• ServerInterface method contracts
• check_auth_*() methods
• check_channel_*() methods
• get_allowed_auths() - auth method advertisement
• SubsystemHandler base class

10. File Operations (LOW)

`paramiko/file.py` (18.6KB)

Priority: LOW - Base file abstraction

Must Test:

• BufferedFile read/write operations
• Line-oriented I/O
• Seek operations
• Iterator protocol

Edge Cases and Error Scenarios

Security Edge Cases

1. Authentication Bypass Attempts

• Sending success messages without proper auth
• Replaying authentication packets
• Timing attacks on password comparison

2. Key Validation

• Malformed key data
• Keys with invalid parameters
• Certificate validation failures
• Expired certificates

3. Protocol Violations

• Out-of-sequence messages
• Invalid message types
• Oversized packets
• Malformed packet structure

Resource Exhaustion

1. Memory

• Very large packets
• Excessive channel creation
• Large file transfers
• Unbounded buffers

2. File Descriptors

• Many concurrent channels
• Agent forwarding chains
• Port forwarding connections

3. CPU

• Expensive key operations
• Compression bombs
• Rekey storms

Network Conditions

1. Connection Issues

• Sudden disconnection
• Partial packet delivery
• High latency
• Packet reordering

2. Timeout Scenarios

• Handshake timeout
• Authentication timeout
• Keep-alive timeout
• Channel operation timeout

Platform-Specific

1. Windows

• Named pipe operations
• Pageant integration
• Security descriptor handling
• Path handling differences

2. Unix

• Unix socket permissions
• Signal handling
• Fork safety

Configuration Edge Cases

1. Malformed Config

• Syntax errors
• Invalid directives
• Circular includes
• Missing required values

2. Token Expansion

• Undefined tokens
• Recursive expansion
• Special characters in values

Test Data Strategy

Key Material

Location: tests/_support/, tests/*.key

Coverage:

• RSA keys (various sizes: 1024, 2048, 4096)
• ECDSA keys (P-256, P-384, P-521)
• Ed25519 keys
• Encrypted keys (various ciphers)
• Keys with certificates
• Malformed keys (for negative testing)

Generation Strategy:

• Use existing test keys where possible
• Generate additional keys programmatically in test setup
• Include keys with unusual properties (padding, encoding)

Configuration Files

Location: tests/configs/

Coverage (already extensive):

• Basic configs
• Match directives (all types)
• Canonicalization scenarios
• Token expansion examples
• Complex multi-host configs

Strategy:

• Reuse existing 40+ config files
• Add configs for untested edge cases
• Programmatically generate configs for parameterized tests

SFTP Test Data

Strategy:

• Small files (0 bytes, 1 byte, typical sizes)
• Large files (>1MB, >100MB for performance tests)
• Binary and text files
• Files with special names (unicode, spaces, special chars)
• Symlinks and directory structures
• Generate in test setup, clean in teardown

Network Packet Data

Strategy:

• Capture real SSH packets for replay tests
• Programmatically construct packets for specific scenarios
• Use paramiko.Message to build test packets
• Include malformed packets for robustness testing

Mock Objects

Strategy:

• Mock socket for network operations
• Mock os and pathlib for filesystem operations
• Mock cryptography primitives for deterministic tests
• Mock invoke for ProxyCommand tests
• Use unittest.mock.patch with context managers

Fixtures (in `conftest.py`)

Existing:

• socket - mocked socket module
• Server/client pairs for integration tests

Recommended Additions:

• temp_key_file - temporary key file with cleanup
• ssh_config - temporary config file
• sftp_server - mock SFTP server
• transport_pair - connected transport pair
• authenticated_transport - post-auth transport

Test Organization

Directory Structure

tests/
├── unit/                    # Pure unit tests
│   ├── test_auth_*.py
│   ├── test_key_*.py
│   ├── test_message.py
│   ├── test_packet.py
│   └── test_util.py
├── integration/             # Integration tests
│   ├── test_client_server.py
│   ├── test_sftp_integration.py
│   └── test_transport_integration.py
├── security/                # Security-focused tests
│   ├── test_auth_bypass.py
│   ├── test_timing_attacks.py
│   └── test_protocol_violations.py
├── performance/             # Performance benchmarks
│   └── test_throughput.py
└── _support/                # Test data and utilities

Naming Conventions

• Test files: test_<module>.py
• Test classes: Test<Feature>
• Test methods: test_<scenario>_<expected_result>
• Fixtures: <resource>_<state> (e.g., authenticated_client)

Markers

@pytest.mark.unit
@pytest.mark.integration
@pytest.mark.security
@pytest.mark.slow
@pytest.mark.windows_only
@pytest.mark.unix_only
@pytest.mark.requires_agent

Continuous Integration

Test Execution Strategy

1. Fast Unit Tests: Run on every commit (~5 min)

2. Integration Tests: Run on PR (~15 min)

3. Full Suite: Run nightly (~30 min)

4. Security Tests: Run on security-related changes

5. Performance Tests: Run weekly, track trends

Coverage Reporting

• Generate coverage reports on every CI run
• Fail if coverage drops below threshold
• Track coverage trends over time
• Highlight uncovered critical paths

Matrix Testing

• Python versions: 3.9, 3.10, 3.11, 3.12, 3.13
• Operating systems: Ubuntu, Windows, macOS
• Cryptography versions: minimum supported, latest

This test plan provides comprehensive coverage of Paramiko's critical functionality while prioritizing security-sensitive components and complex business logic. The existing test infrastructure should be leveraged and extended following these guidelines.