Implement IPv4 and IPv6 Address Pattern Detection in Semantic Classifier

[unclesp1d3r]

Summary

Implement comprehensive IPv4 and IPv6 address pattern detection and validation within the semantic classification system to identify and tag IP addresses found in binary strings.

Context

The semantic classifier currently supports URL and domain detection. IP addresses are a critical type of network indicator that appear frequently in binaries (C&C addresses, configuration endpoints, telemetry servers, hardcoded network targets). Adding IPv4 and IPv6 detection will enable security analysts and reverse engineers to quickly identify potential network indicators of compromise (IOCs).

Current State

• Tag::IPv4 and Tag::IPv6 enum variants are already defined in src/types.rs (lines 18-19)
• src/classification/mod.rs exists but is currently empty
• The semantic tagging infrastructure is in place but needs pattern matching implementation
• Architecture supports regex-based classification per concept.md

Dependencies

• Blocked by: URL and Domain Classification (Implement URL and Domain Pattern Matching in Semantic Classification System #15 or related)
  • The implementation pattern established for URL/Domain detection should be followed for consistency
  • Shared validation utilities may be needed

Proposed Solution

Implementation Approach

Implement IP address detection in src/classification/mod.rs (or a dedicated submodule) with the following components:

1. IPv4 Pattern Matching

Pattern: XXX.XXX.XXX.XXX where each octet is 0-255

Validation Rules:

• Four octets separated by dots
• Each octet must be 0-255 (no leading zeros except for "0" itself)
• No leading/trailing dots
• Exclude invalid ranges for context (e.g., 0.0.0.0, 255.255.255.255 may be flagged with lower scores)

Example Valid: 192.168.1.1, 10.0.0.1, 172.16.0.1, 8.8.8.8

Example Invalid: 256.1.1.1, 192.168.1, 192.168.1.1.1, 192.168.01.1 (leading zero)

Regex Pattern (starting point):

\b(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\b

2. IPv6 Pattern Matching

Format Support:

• Full notation: 2001:0db8:85a3:0000:0000:8a2e:0370:7334
• Compressed notation: 2001:db8:85a3::8a2e:370:7334
• Mixed notation (IPv4-mapped): ::ffff:192.0.2.1
• Loopback: ::1
• Link-local: fe80::1

Validation Rules:

• Eight groups of 4 hexadecimal digits separated by colons
• Double colon :: allowed once to represent consecutive zeros
• Trailing/embedded IPv4 addresses in mixed notation
• Case-insensitive hex digits (a-f, A-F)

Example Valid:

• 2001:db8::1
• fe80::1
• ::1
• 2001:0db8:85a3::8a2e:0370:7334
• ::ffff:192.0.2.1

Implementation Note: IPv6 regex validation is complex. Consider using the ipnetwork or std::net::IpAddr for validation after initial pattern matching.

3. Classification Function Structure

pub fn classify_string(text: &str) -> Vec<Tag> {
    let mut tags = Vec::new();
    
    if is_ipv4_address(text) {
        tags.push(Tag::IPv4);
    }
    
    if is_ipv6_address(text) {
        tags.push(Tag::IPv6);
    }
    
    // Add other classification logic (URL, Domain, etc.)
    
    tags
}

fn is_ipv4_address(text: &str) -> bool {
    // Implementation with regex + validation
}

fn is_ipv6_address(text: &str) -> bool {
    // Implementation with regex + std::net::Ipv6Addr parsing
}

4. Integration with Scoring System

IP addresses should receive semantic boost per concept.md ranking algorithm:

• IPv4/IPv6 in private ranges: +2 score (internal network indicators)
• IPv4/IPv6 in public ranges: +3 to +5 score (potential C&C, external endpoints)
• IPv4 in special ranges (loopback, multicast): +1 score (informational)

Technical Considerations

1. False Positives:

   • Version numbers may look like IPs: 1.2.3.4
   • Add context checks: IPs in networking sections get higher confidence
   • Consider excluding common version patterns (all octets < 20)

2. Performance:

   • Use compiled regex with regex crate
   • Consider aho-corasick for multi-pattern matching if combined with URL/Domain
   • Lazy static initialization for regex patterns

3. Dependencies:

   • regex = "1.10" (already in use per architecture)
   • Optional: ipnetwork = "0.20" or use std::net for validation

4. Port Handling:

   • Decide if 192.168.1.1:8080 should be tagged as IPv4
   • Suggest: Strip port suffix before validation, still tag as IPv4

Testing Requirements

Unit Tests

Create src/classification/tests.rs or inline tests with coverage for:

IPv4 Tests:

• ✅ Valid addresses: 192.168.1.1, 10.0.0.1, 8.8.8.8, 1.1.1.1
• ✅ Edge cases: 0.0.0.0, 255.255.255.255, 127.0.0.1
• ❌ Invalid: 256.1.1.1, 192.168.1, 192.168.1.1.1, 999.999.999.999
• ❌ Leading zeros: 192.168.01.1
• ❌ Version numbers: 1.2.3.4 (context-dependent)
• ✅ With ports: 192.168.1.1:8080 (should extract IP)

IPv6 Tests:

• ✅ Full notation: 2001:0db8:85a3:0000:0000:8a2e:0370:7334
• ✅ Compressed: 2001:db8::1, ::1, fe80::1
• ✅ Mixed notation: ::ffff:192.0.2.1, 64:ff9b::192.0.2.1
• ✅ All zeros: ::
• ❌ Invalid: gggg::1, 2001:db8::1::2 (double ::), 2001:db8:1
• ✅ With ports/brackets: [2001:db8::1]:8080

Integration Tests:

• Extract IPs from sample binary strings (mix of text, URLs with IPs, config strings)
• Verify tagging applied correctly to FoundString objects
• Test scoring boosts are applied

Documentation

• Add rustdoc comments to classification functions
• Update concept.md with IP classification details
• Add examples to README.md showing IP detection

Acceptance Criteria

• IPv4 pattern matching implemented with validation
• IPv6 pattern matching implemented with validation
• Unit tests cover valid, invalid, and edge cases for both formats
• Integration with semantic tagging system (Tag::IPv4, Tag::IPv6)
• False positive mitigation strategies implemented
• Scoring boost integrated into ranking algorithm
• Documentation updated (rustdoc, README, concept.md)
• No performance regression in string extraction pipeline

References

• RFC 791 - Internet Protocol (IPv4)
• RFC 4291 - IPv6 Addressing Architecture
• RFC 5952 - IPv6 Address Text Representation
• Rust std::net::IpAddr documentation

Related Issues

• Implement URL and Domain Pattern Matching in Semantic Classification System #15 (or relevant): URL and Domain Classification (blocking)
• Future: Network endpoint clustering/analysis

---

Task-ID: stringy-analyzer/ip-address-classification
Requirements: 3.3
Estimated Effort: 2-3 days (implementation + comprehensive testing)

[unclesp1d3r]

@coderabbitai Enhance this issue body with additional context and a proposed solution. Improve the issue title and assign the proper labels and other metadata.

[traycerai]

Plan

Observations

Current State Analysis

The codebase has a well-established foundation:

1. Type System Complete: Tag::IPv4 and Tag::IPv6 are already defined in src/types.rs (lines 18-19) with proper serde serialization
2. Classification Module Empty: src/classification/mod.rs contains only a comment, ready for implementation
3. Architecture Defined: Issue Implement URL and Domain Pattern Matching in Semantic Classification System #15 establishes the pattern with SemanticClassifier struct using regex + lazy_static
4. Dependencies Status: regex crate is already in use per architecture; lazy_static may need to be added
5. Documentation Exists: docs/src/classification.md already documents IPv4/IPv6 patterns (lines 29-35)
6. Testing Conventions: The project uses inline #[cfg(test)] modules for unit tests, as seen in all container parsers
7. Blocked Dependency: Issue Implement URL and Domain Pattern Matching in Semantic Classification System #15 (URL/Domain classification) is the blocking dependency, but both can share the same SemanticClassifier structure

Key Requirements from Specs

From the GitHub issue requirements:

• Requirement 3.3: "WHEN a string matches an IPv4 or IPv6 pattern THEN the system SHALL tag it as 'ipv4' or 'ipv6'"
• Story Points: 3 (estimated effort: 2-3 days)
• Priority: Medium
• Labels: good first issue, area:analyzer, type:enhancement, status:backlog, lang:rust, needs:tests

From concept.md: Classification should use "Regex/automata buckets: url, domain, ipv4/6"

Implementation Strategy

Following the pattern from issue #15, implement a SemanticClassifier in src/classification/semantic.rs that handles both URL/Domain (from #15) and IPv4/IPv6 detection. The approach uses:

1. Two-stage validation: Regex pre-filter → std::net::IpAddr validation for correctness
2. Port handling: Strip port suffixes before validation (e.g., 192.168.1.1:8080 → 192.168.1.1)
3. False positive mitigation: Context-aware checks for version numbers (reject if all octets < 20)
4. Lazy static patterns: Compile regex once, reuse across calls for performance
5. IPv6 bracket handling: Support bracketed notation like [::1] and [::1]:8080

Approach

Implement IPv4 and IPv6 address pattern detection in the semantic classification system by:

1. Adding required dependencies (regex, lazy_static) to Cargo.toml if not already present
2. Creating src/classification/semantic.rs with SemanticClassifier struct
3. Implementing IPv4 detection using regex + octet validation via std::net::Ipv4Addr
4. Implementing IPv6 detection using regex + validation via std::net::Ipv6Addr
5. Handling edge cases (ports, brackets, false positives)
6. Updating src/classification/mod.rs to export the classifier
7. Adding comprehensive unit tests covering valid/invalid cases
8. Updating documentation (rustdoc, README.md, concept.md)

This follows the established pattern from issue #15 and integrates seamlessly with the existing type system.

Reasoning

The GitHub ticket provides comprehensive requirements including validation rules, regex patterns, test cases, and acceptance criteria. The implementation should follow the established pattern from issue #15 while addressing the specific needs for IP address detection: two-stage validation (regex + std::net parsing), port handling, false positive mitigation for version numbers, and comprehensive test coverage for both IPv4 and IPv6 formats.

Mermaid Diagram

sequenceDiagram
    participant User as User/Extraction Pipeline
    participant SC as SemanticClassifier
    participant Regex as Regex Patterns (lazy_static)
    participant StdNet as std::net::IpAddr
    participant Tags as Vec<Tag>

    User->>SC: classify("192.168.1.1:8080")
    SC->>SC: classify_ip_addresses()
    
    SC->>SC: is_ipv4_address()
    SC->>SC: strip_port() → "192.168.1.1"
    SC->>Regex: IPV4_REGEX.is_match()
    Regex-->>SC: true
    SC->>StdNet: Ipv4Addr::from_str("192.168.1.1")
    StdNet-->>SC: Ok(192.168.1.1)
    SC->>SC: is_likely_version_number()
    SC-->>SC: false (octets not all < 20)
    SC-->>SC: true (valid IPv4)
    
    SC->>SC: is_ipv6_address()
    SC->>Regex: IPV6_REGEX.is_match()
    Regex-->>SC: false
    SC-->>SC: false (not IPv6)
    
    SC->>Tags: push(Tag::IPv4)
    SC-->>User: vec![Tag::IPv4]
    
    Note over User,Tags: For IPv6 with brackets: [::1]:8080
    User->>SC: classify("[::1]:8080")
    SC->>SC: is_ipv6_address()
    SC->>SC: strip_ipv6_brackets() → "::1:8080"
    SC->>SC: strip_port() → "::1"
    SC->>Regex: IPV6_REGEX.is_match()
    Regex-->>SC: true
    SC->>StdNet: Ipv6Addr::from_str("::1")
    StdNet-->>SC: Ok(::1)
    SC->>Tags: push(Tag::IPv6)
    SC-->>User: vec![Tag::IPv6]

Loading

Proposed File Changes

file:Cargo.toml (Modify)

Add required dependencies to the [dependencies] section:

1. regex = "1.11" - For pattern matching IPv4/IPv6 addresses and other semantic patterns (verify if already present)
2. lazy_static = "1.5" - For caching compiled regex patterns to avoid recompilation (verify if already present)

These dependencies enable efficient semantic classification as specified in the architecture documentation. The regex crate provides efficient pattern matching, while lazy_static enables one-time compilation of regex patterns for performance.

file:src/classification/semantic.rs (New)

Create the semantic classifier module with IPv4 and IPv6 detection capabilities:

Structure:

1. Imports:

   • regex::Regex
   • lazy_static::lazy_static
   • std::net::{IpAddr, Ipv4Addr, Ipv6Addr}
   • crate::types::Tag

2. Lazy Static Regex Patterns:

   • IPV4_REGEX: Pattern \b(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\b for matching IPv4 addresses with proper octet validation (0-255)
   • IPV6_REGEX: Pattern to match IPv6 addresses including compressed notation (::1), full notation (2001:0db8:85a3:0000:0000:8a2e:0370:7334), and mixed notation (::ffff:192.0.2.1)
   • PORT_SUFFIX_REGEX: Pattern :[0-9]{1,5}$ to detect and strip port numbers
   • IPV6_BRACKETS_REGEX: Pattern ^\[(.+)\] to handle bracketed IPv6 addresses like [::1]

3. SemanticClassifier Struct: Empty struct that will hold classification logic

4. Implementation Methods:

   is_ipv4_address(text: &str) -> bool:

   • Strip port suffix if present using regex
   • Check if text matches IPv4_REGEX pattern
   • Validate using Ipv4Addr::from_str() to ensure proper format
   • Apply false positive mitigation: reject if all octets are < 20 (likely version number like 1.2.3.4)
   • Return true only if all validations pass

   is_ipv6_address(text: &str) -> bool:

   • Strip bracketed notation if present (e.g., [::1] → ::1)
   • Strip port suffix if present
   • Check if text matches IPv6_REGEX pattern
   • Validate using Ipv6Addr::from_str() for canonical validation
   • Return true if validation passes

   classify_ip_addresses(text: &str) -> Vec:

   • Create empty tags vector
   • Check for IPv4 using is_ipv4_address(), push Tag::IPv4 if matched
   • Check for IPv6 using is_ipv6_address(), push Tag::IPv6 if matched
   • Return tags vector (may contain 0, 1, or 2 tags)

   classify(text: &str) -> Vec:

   • Main entry point for classification
   • Call classify_ip_addresses() to get IP tags
   • Future: Will also call URL/Domain classification from issue Implement URL and Domain Pattern Matching in Semantic Classification System #15
   • Return combined tags

5. Helper Functions:

   • strip_port(text: &str) -> &str: Remove :port suffix if present
   • strip_ipv6_brackets(text: &str) -> &str: Remove [ and ] from IPv6 addresses
   • is_likely_version_number(text: &str) -> bool: Check if IPv4-like string is actually a version number

6. Unit Tests (in #[cfg(test)] module):

   IPv4 Tests:

   • test_ipv4_valid_addresses: Test 192.168.1.1, 10.0.0.1, 8.8.8.8, 1.1.1.1, 127.0.0.1, 0.0.0.0, 255.255.255.255
   • test_ipv4_invalid_addresses: Test 256.1.1.1, 192.168.1, 192.168.1.1.1, 999.999.999.999, 192.168.01.1 (leading zeros)
   • test_ipv4_with_port: Test 192.168.1.1:8080, 10.0.0.1:443 (should extract IP)
   • test_ipv4_version_numbers: Test 1.2.3.4, 2.0.1.0 (should reject as version numbers)
   • test_ipv4_edge_cases: Test boundary values and special addresses

   IPv6 Tests:

   • test_ipv6_full_notation: Test 2001:0db8:85a3:0000:0000:8a2e:0370:7334
   • test_ipv6_compressed: Test 2001:db8::1, ::1, fe80::1, ::
   • test_ipv6_mixed_notation: Test ::ffff:192.0.2.1, 64:ff9b::192.0.2.1
   • test_ipv6_invalid: Test gggg::1, 2001:db8::1::2 (double ::), 2001:db8:1
   • test_ipv6_with_brackets: Test [2001:db8::1], [::1]
   • test_ipv6_with_port: Test [2001:db8::1]:8080

   Integration Tests:

   • test_classify_ipv4: Test that classify() returns vec![Tag::IPv4] for valid IPv4
   • test_classify_ipv6: Test that classify() returns vec![Tag::IPv6] for valid IPv6
   • test_classify_no_ip: Test that classify() returns empty vector for non-IP strings
   • test_classify_multiple_patterns: Test strings that might match multiple patterns

Follow the testing pattern established in existing container parsers with inline #[cfg(test)] modules.

file:src/classification/mod.rs (Modify)

Replace the existing comment with proper module structure:

1. Module Declaration: Add pub mod semantic; to declare the semantic classification submodule

2. Re-exports: Add pub use semantic::SemanticClassifier; to make the classifier easily accessible from classification::SemanticClassifier

3. Module Documentation: Add rustdoc comments explaining:

   • Purpose: Semantic analysis and tagging of extracted strings
   • Current capabilities: IPv4/IPv6 address detection
   • Future capabilities: URL, Domain, file paths, GUIDs, etc. (from issue Implement URL and Domain Pattern Matching in Semantic Classification System #15 and related)
   • Usage example showing how to create a classifier and classify strings

file:docs/src/classification.md (Modify)

Update the IP Addresses section to reflect the actual implementation:

1. Update IPv4 Pattern: Replace the simplified pattern with the actual regex used: \b(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\b

2. Add Validation Details: Document that the implementation uses two-stage validation:

   • Regex pre-filter for performance
   • std::net::IpAddr validation for correctness

3. Document Port Handling: Add note that IP addresses with ports (e.g., 192.168.1.1:8080) are supported by stripping the port suffix

4. Document IPv6 Bracket Handling: Add note that bracketed IPv6 addresses (e.g., [::1]) are supported

5. Document False Positive Mitigation: Explain that version numbers like 1.2.3.4 are filtered out using heuristics (all octets < 20)

6. Add Implementation Note: Reference src/classification/semantic.rs as the implementation location

7. Update Examples: Ensure examples match the test cases in the implementation

file:README.md (Modify)

Update the development status section to reflect IPv4/IPv6 classification implementation:

1. Update Classification Status: Change the line about semantic classification to indicate that IPv4/IPv6 detection is now implemented:

   • "🚧 Semantic Classification: IPv4/IPv6 detection implemented; URL, domain, path, GUID pattern matching in progress (types defined)"

2. Update Feature List: Ensure the "Smart classification" bullet point mentions that IPv4/IPv6 detection is functional:

   • Change "URLs, domains, IPs" to "URLs, domains, IPv4/IPv6 addresses (implemented)"

This provides accurate status information to users and contributors about which classification features are available.

Import In IDE

🤖 Prompt for AI Agents

### Observations

## Current State Analysis

The codebase has a well-established foundation:

1. **Type System Complete**: `Tag::IPv4` and `Tag::IPv6` are already defined in `src/types.rs` (lines 18-19) with proper serde serialization
2. **Classification Module Empty**: `src/classification/mod.rs` contains only a comment, ready for implementation
3. **Architecture Defined**: Issue #15 establishes the pattern with `SemanticClassifier` struct using regex + lazy_static
4. **Dependencies Status**: `regex` crate is already in use per architecture; `lazy_static` may need to be added
5. **Documentation Exists**: `docs/src/classification.md` already documents IPv4/IPv6 patterns (lines 29-35)
6. **Testing Conventions**: The project uses inline `#[cfg(test)]` modules for unit tests, as seen in all container parsers
7. **Blocked Dependency**: Issue #15 (URL/Domain classification) is the blocking dependency, but both can share the same `SemanticClassifier` structure

## Key Requirements from Specs

From the GitHub issue requirements:
- **Requirement 3.3**: "WHEN a string matches an IPv4 or IPv6 pattern THEN the system SHALL tag it as 'ipv4' or 'ipv6'"
- **Story Points**: 3 (estimated effort: 2-3 days)
- **Priority**: Medium
- **Labels**: good first issue, area:analyzer, type:enhancement, status:backlog, lang:rust, needs:tests

From `concept.md`: Classification should use "Regex/automata buckets: `url`, `domain`, `ipv4/6`"

## Implementation Strategy

Following the pattern from issue #15, implement a `SemanticClassifier` in `src/classification/semantic.rs` that handles both URL/Domain (from #15) and IPv4/IPv6 detection. The approach uses:

1. **Two-stage validation**: Regex pre-filter → `std::net::IpAddr` validation for correctness
2. **Port handling**: Strip port suffixes before validation (e.g., `192.168.1.1:8080` → `192.168.1.1`)
3. **False positive mitigation**: Context-aware checks for version numbers (reject if all octets < 20)
4. **Lazy static patterns**: Compile regex once, reuse across calls for performance
5. **IPv6 bracket handling**: Support bracketed notation like `[::1]` and `[::1]:8080`

### Approach

Implement IPv4 and IPv6 address pattern detection in the semantic classification system by:

1. Adding required dependencies (`regex`, `lazy_static`) to `Cargo.toml` if not already present
2. Creating `src/classification/semantic.rs` with `SemanticClassifier` struct
3. Implementing IPv4 detection using regex + octet validation via `std::net::Ipv4Addr`
4. Implementing IPv6 detection using regex + validation via `std::net::Ipv6Addr`
5. Handling edge cases (ports, brackets, false positives)
6. Updating `src/classification/mod.rs` to export the classifier
7. Adding comprehensive unit tests covering valid/invalid cases
8. Updating documentation (rustdoc, README.md, concept.md)

This follows the established pattern from issue #15 and integrates seamlessly with the existing type system.

### Reasoning

The GitHub ticket provides comprehensive requirements including validation rules, regex patterns, test cases, and acceptance criteria. The implementation should follow the established pattern from issue #15 while addressing the specific needs for IP address detection: two-stage validation (regex + std::net parsing), port handling, false positive mitigation for version numbers, and comprehensive test coverage for both IPv4 and IPv6 formats.

## Mermaid Diagram

```mermaid
sequenceDiagram
    participant User as User/Extraction Pipeline
    participant SC as SemanticClassifier
    participant Regex as Regex Patterns (lazy_static)
    participant StdNet as std::net::IpAddr
    participant Tags as Vec<Tag>

    User->>SC: classify("192.168.1.1:8080")
    SC->>SC: classify_ip_addresses()
    
    SC->>SC: is_ipv4_address()
    SC->>SC: strip_port() → "192.168.1.1"
    SC->>Regex: IPV4_REGEX.is_match()
    Regex-->>SC: true
    SC->>StdNet: Ipv4Addr::from_str("192.168.1.1")
    StdNet-->>SC: Ok(192.168.1.1)
    SC->>SC: is_likely_version_number()
    SC-->>SC: false (octets not all < 20)
    SC-->>SC: true (valid IPv4)
    
    SC->>SC: is_ipv6_address()
    SC->>Regex: IPV6_REGEX.is_match()
    Regex-->>SC: false
    SC-->>SC: false (not IPv6)
    
    SC->>Tags: push(Tag::IPv4)
    SC-->>User: vec![Tag::IPv4]
    
    Note over User,Tags: For IPv6 with brackets: [::1]:8080
    User->>SC: classify("[::1]:8080")
    SC->>SC: is_ipv6_address()
    SC->>SC: strip_ipv6_brackets() → "::1:8080"
    SC->>SC: strip_port() → "::1"
    SC->>Regex: IPV6_REGEX.is_match()
    Regex-->>SC: true
    SC->>StdNet: Ipv6Addr::from_str("::1")
    StdNet-->>SC: Ok(::1)
    SC->>Tags: push(Tag::IPv6)
    SC-->>User: vec![Tag::IPv6]
```

## Proposed File Changes

### file:Cargo.toml (Modify)

Add required dependencies to the `[dependencies]` section:

1. **regex = "1.11"** - For pattern matching IPv4/IPv6 addresses and other semantic patterns (verify if already present)
2. **lazy_static = "1.5"** - For caching compiled regex patterns to avoid recompilation (verify if already present)

These dependencies enable efficient semantic classification as specified in the architecture documentation. The `regex` crate provides efficient pattern matching, while `lazy_static` enables one-time compilation of regex patterns for performance.

### file:src/classification/semantic.rs (New)

Create the semantic classifier module with IPv4 and IPv6 detection capabilities:

**Structure**:

1. **Imports**: 
   - `regex::Regex`
   - `lazy_static::lazy_static`
   - `std::net::{IpAddr, Ipv4Addr, Ipv6Addr}`
   - `crate::types::Tag`

2. **Lazy Static Regex Patterns**:
   - `IPV4_REGEX`: Pattern `\b(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\b` for matching IPv4 addresses with proper octet validation (0-255)
   - `IPV6_REGEX`: Pattern to match IPv6 addresses including compressed notation (`::1`), full notation (`2001:0db8:85a3:0000:0000:8a2e:0370:7334`), and mixed notation (`::ffff:192.0.2.1`)
   - `PORT_SUFFIX_REGEX`: Pattern `:[0-9]{1,5}$` to detect and strip port numbers
   - `IPV6_BRACKETS_REGEX`: Pattern `^\[(.+)\]` to handle bracketed IPv6 addresses like `[::1]`

3. **SemanticClassifier Struct**: Empty struct that will hold classification logic

4. **Implementation Methods**:

   **is_ipv4_address(text: &str) -> bool**:
   - Strip port suffix if present using regex
   - Check if text matches IPv4_REGEX pattern
   - Validate using `Ipv4Addr::from_str()` to ensure proper format
   - Apply false positive mitigation: reject if all octets are < 20 (likely version number like 1.2.3.4)
   - Return true only if all validations pass

   **is_ipv6_address(text: &str) -> bool**:
   - Strip bracketed notation if present (e.g., `[::1]` → `::1`)
   - Strip port suffix if present
   - Check if text matches IPv6_REGEX pattern
   - Validate using `Ipv6Addr::from_str()` for canonical validation
   - Return true if validation passes

   **classify_ip_addresses(text: &str) -> Vec<Tag>**:
   - Create empty tags vector
   - Check for IPv4 using `is_ipv4_address()`, push `Tag::IPv4` if matched
   - Check for IPv6 using `is_ipv6_address()`, push `Tag::IPv6` if matched
   - Return tags vector (may contain 0, 1, or 2 tags)

   **classify(text: &str) -> Vec<Tag>**:
   - Main entry point for classification
   - Call `classify_ip_addresses()` to get IP tags
   - Future: Will also call URL/Domain classification from issue #15
   - Return combined tags

5. **Helper Functions**:
   - `strip_port(text: &str) -> &str`: Remove `:port` suffix if present
   - `strip_ipv6_brackets(text: &str) -> &str`: Remove `[` and `]` from IPv6 addresses
   - `is_likely_version_number(text: &str) -> bool`: Check if IPv4-like string is actually a version number

6. **Unit Tests** (in `#[cfg(test)]` module):

   **IPv4 Tests**:
   - `test_ipv4_valid_addresses`: Test `192.168.1.1`, `10.0.0.1`, `8.8.8.8`, `1.1.1.1`, `127.0.0.1`, `0.0.0.0`, `255.255.255.255`
   - `test_ipv4_invalid_addresses`: Test `256.1.1.1`, `192.168.1`, `192.168.1.1.1`, `999.999.999.999`, `192.168.01.1` (leading zeros)
   - `test_ipv4_with_port`: Test `192.168.1.1:8080`, `10.0.0.1:443` (should extract IP)
   - `test_ipv4_version_numbers`: Test `1.2.3.4`, `2.0.1.0` (should reject as version numbers)
   - `test_ipv4_edge_cases`: Test boundary values and special addresses

   **IPv6 Tests**:
   - `test_ipv6_full_notation`: Test `2001:0db8:85a3:0000:0000:8a2e:0370:7334`
   - `test_ipv6_compressed`: Test `2001:db8::1`, `::1`, `fe80::1`, `::`
   - `test_ipv6_mixed_notation`: Test `::ffff:192.0.2.1`, `64:ff9b::192.0.2.1`
   - `test_ipv6_invalid`: Test `gggg::1`, `2001:db8::1::2` (double `::`), `2001:db8:1`
   - `test_ipv6_with_brackets`: Test `[2001:db8::1]`, `[::1]`
   - `test_ipv6_with_port`: Test `[2001:db8::1]:8080`

   **Integration Tests**:
   - `test_classify_ipv4`: Test that `classify()` returns `vec![Tag::IPv4]` for valid IPv4
   - `test_classify_ipv6`: Test that `classify()` returns `vec![Tag::IPv6]` for valid IPv6
   - `test_classify_no_ip`: Test that `classify()` returns empty vector for non-IP strings
   - `test_classify_multiple_patterns`: Test strings that might match multiple patterns

Follow the testing pattern established in existing container parsers with inline `#[cfg(test)]` modules.

### file:src/classification/mod.rs (Modify)

Replace the existing comment with proper module structure:

1. **Module Declaration**: Add `pub mod semantic;` to declare the semantic classification submodule

2. **Re-exports**: Add `pub use semantic::SemanticClassifier;` to make the classifier easily accessible from `classification::SemanticClassifier`

3. **Module Documentation**: Add rustdoc comments explaining:
   - Purpose: Semantic analysis and tagging of extracted strings
   - Current capabilities: IPv4/IPv6 address detection
   - Future capabilities: URL, Domain, file paths, GUIDs, etc. (from issue #15 and related)
   - Usage example showing how to create a classifier and classify strings

### file:docs/src/classification.md (Modify)

Update the IP Addresses section to reflect the actual implementation:

1. **Update IPv4 Pattern**: Replace the simplified pattern with the actual regex used: `\b(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\b`

2. **Add Validation Details**: Document that the implementation uses two-stage validation:
   - Regex pre-filter for performance
   - `std::net::IpAddr` validation for correctness

3. **Document Port Handling**: Add note that IP addresses with ports (e.g., `192.168.1.1:8080`) are supported by stripping the port suffix

4. **Document IPv6 Bracket Handling**: Add note that bracketed IPv6 addresses (e.g., `[::1]`) are supported

5. **Document False Positive Mitigation**: Explain that version numbers like `1.2.3.4` are filtered out using heuristics (all octets < 20)

6. **Add Implementation Note**: Reference `src/classification/semantic.rs` as the implementation location

7. **Update Examples**: Ensure examples match the test cases in the implementation

### file:README.md (Modify)

Update the development status section to reflect IPv4/IPv6 classification implementation:

1. **Update Classification Status**: Change the line about semantic classification to indicate that IPv4/IPv6 detection is now implemented:
   - "🚧 **Semantic Classification**: IPv4/IPv6 detection implemented; URL, domain, path, GUID pattern matching in progress (types defined)"

2. **Update Feature List**: Ensure the "Smart classification" bullet point mentions that IPv4/IPv6 detection is functional:
   - Change "URLs, domains, IPs" to "URLs, domains, IPv4/IPv6 addresses (implemented)"

This provides accurate status information to users and contributors about which classification features are available.

---

Execution Information

Branch: main
Commit: e2eb692

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.