Implement CLI Filtering Arguments for String Extraction Control

[unclesp1d3r]

Overview

This issue implements command-line filtering arguments that give users fine-grained control over string extraction from binary files. These filters are essential for reducing noise and focusing analysis on relevant string types, making Stringy more practical for real-world reverse engineering and malware analysis workflows.

Context

Stringy extracts and categorizes strings from binaries using semantic tags (URLs, file paths, GUIDs, format strings, etc.) and supports multiple encodings (ASCII, UTF-8, UTF-16LE/BE). However, without filtering capabilities, users receive all extracted strings regardless of their analysis goals. For example:

• Malware analysts often need only URLs and network indicators
• Reverse engineers may focus on format strings and error messages
• Performance: Filtering reduces output size and processing overhead
• Pipelines: Filtered JSON output enables targeted downstream processing

Requirements

This implements requirements 7.1, 7.2, 7.3, and 7.4 from the specification.

Proposed Solution

CLI Arguments

Implement the following filtering arguments using the clap crate:

1. --min-len <LENGTH>

   • Filter strings shorter than the specified length
   • Type: usize
   • Default: 4 (consistent with standard strings command)
   • Example: stringy --min-len 8 binary.exe

2. --enc <ENCODINGS>

   • Comma-separated list of encodings to include
   • Type: Vec<String>
   • Valid values: ascii, utf8, utf16le, utf16be
   • Default: all encodings
   • Example: stringy --enc ascii,utf8 binary.exe

3. --only-tags <TAGS>

   • Comma-separated list of semantic tags to include (whitelist)
   • Type: Vec<String>
   • Valid values: url, domain, ip, filepath, registry, guid, useragent, fmt, base64, crypto
   • Mutually exclusive with --notags
   • Example: stringy --only-tags url,domain,ip binary.exe

4. --notags

   • Exclude strings without any semantic tags (show only classified strings)
   • Type: bool flag
   • Mutually exclusive with --only-tags
   • Example: stringy --notags binary.exe

Implementation Approach

1. Argument Parsing (src/cli.rs or main CLI module)

   • Define filtering arguments in the clap Args struct
   • Implement validation for encoding names and tag names
   • Add mutual exclusivity check for --only-tags and --notags

2. Filter Configuration (src/types.rs or new src/filter.rs)

   • Create a FilterConfig struct to hold parsed filter settings
   • Implement FilterConfig::from_args() to convert CLI args
   • Add validation methods for encoding and tag names

3. Filtering Logic (in string extraction pipeline)

   • Apply min-len filter during or after extraction
   • Apply encoding filter by skipping unwanted encoding attempts
   • Apply tag filters when assembling final output
   • Ensure filtering preserves ranking/scoring when applicable

4. Error Handling

   • Invalid encoding names → clear error message with valid options
   • Invalid tag names → clear error message with valid options
   • Conflicting --only-tags and --notags → clap conflict group

Example Usage

# Extract only URLs and domains with minimum length 10
stringy --only-tags url,domain --min-len 10 malware.exe

# Extract only UTF-16 strings (common in PE files)
stringy --enc utf16le malware.exe

# Extract only tagged/classified strings
stringy --notags suspicious.elf

# Combine filters for precision
stringy --min-len 8 --enc ascii,utf8 --only-tags filepath,registry binary.dll

Acceptance Criteria

• --min-len argument filters strings by minimum length
• --enc argument accepts comma-separated encoding list and filters accordingly
• --only-tags argument accepts comma-separated tag list and shows only matching strings
• --notags flag excludes untagged strings
• --only-tags and --notags are mutually exclusive (enforced by clap)
• Invalid encoding names produce helpful error messages
• Invalid tag names produce helpful error messages
• Unit tests cover:
  • Argument parsing for all flags
  • Filter configuration validation
  • Filtering logic for each argument type
  • Mutual exclusivity enforcement
  • Edge cases (empty results, no matches, etc.)
• Documentation updated with filtering examples
• Filtering works correctly in both human-readable and JSON output modes

Dependencies

• Blocked by: Basic CLI Structure (must be completed first)
• Depends on: String extraction and tagging system (framework exists)

Testing Strategy

1. Unit Tests (tests/cli_filtering.rs):

   • Parse valid and invalid argument combinations
   • Validate filter configuration creation
   • Test filter application logic in isolation

2. Integration Tests:

   • Run stringy with various filter combinations on test binaries
   • Verify output contains only expected strings
   • Test edge cases (no matches, all filtered out, etc.)

Task ID

stringy-analyzer/filtering-cli-arguments

Related Issues

• Basic CLI Structure (prerequisite)
• String Extraction Engine (#TBD)
• Semantic Tagging System (#TBD)

[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]

Warning

Rate limit exceeded. Please try after 1379 seconds.

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Fetch issue #30 details
gh issue view 30 --json title,body,labels,assignees,milestone,state

# Get repository information to understand the project context
gh repo view --json description,name,owner

# Check for existing labels in the repository
gh label list --json name,description --limit 100

# Look at README for project context
cat README.md 2>/dev/null || echo "README.md not found"

# Check if there's a CONTRIBUTING or docs about requirements
fd -t f "requirement" -e md -e txt --max-depth 3 --exec cat {}

# Look for any CLI-related files to understand the structure
fd -t f "cli" -i --max-depth 3

Length of output: 10660

---

🏁 Script executed:

#!/bin/bash
# Update the issue with enhanced content

gh issue edit 30 \
  --title "Implement CLI Filtering Arguments for String Extraction Control" \
  --body "## Overview

This issue implements command-line filtering arguments that give users fine-grained control over string extraction from binary files. These filters are essential for reducing noise and focusing analysis on relevant string types, making Stringy more practical for real-world reverse engineering and malware analysis workflows.

## Context

Stringy extracts and categorizes strings from binaries using semantic tags (URLs, file paths, GUIDs, format strings, etc.) and supports multiple encodings (ASCII, UTF-8, UTF-16LE/BE). However, without filtering capabilities, users receive all extracted strings regardless of their analysis goals. For example:

- **Malware analysts** often need only URLs and network indicators
- **Reverse engineers** may focus on format strings and error messages
- **Performance**: Filtering reduces output size and processing overhead
- **Pipelines**: Filtered JSON output enables targeted downstream processing

## Requirements

This implements requirements **7.1, 7.2, 7.3, and 7.4** from the specification.

## Proposed Solution

### CLI Arguments

Implement the following filtering arguments using the \`clap\` crate:

1. **\`--min-len <LENGTH>\`**
   - Filter strings shorter than the specified length
   - Type: \`usize\`
   - Default: \`4\` (consistent with standard \`strings\` command)
   - Example: \`stringy --min-len 8 binary.exe\`

2. **\`--enc <ENCODINGS>\`**
   - Comma-separated list of encodings to include
   - Type: \`Vec<String>\`
   - Valid values: \`ascii\`, \`utf8\`, \`utf16le\`, \`utf16be\`
   - Default: all encodings
   - Example: \`stringy --enc ascii,utf8 binary.exe\`

3. **\`--only-tags <TAGS>\`**
   - Comma-separated list of semantic tags to include (whitelist)
   - Type: \`Vec<String>\`
   - Valid values: \`url\`, \`domain\`, \`ip\`, \`filepath\`, \`registry\`, \`guid\`, \`useragent\`, \`fmt\`, \`base64\`, \`crypto\`
   - Mutually exclusive with \`--notags\`
   - Example: \`stringy --only-tags url,domain,ip binary.exe\`

4. **\`--notags\`**
   - Exclude strings without any semantic tags (show only classified strings)
   - Type: \`bool\` flag
   - Mutually exclusive with \`--only-tags\`
   - Example: \`stringy --notags binary.exe\`

### Implementation Approach

1. **Argument Parsing** (\`src/cli.rs\` or main CLI module)
   - Define filtering arguments in the clap \`Args\` struct
   - Implement validation for encoding names and tag names
   - Add mutual exclusivity check for \`--only-tags\` and \`--notags\`

2. **Filter Configuration** (\`src/types.rs\` or new \`src/filter.rs\`)
   - Create a \`FilterConfig\` struct to hold parsed filter settings
   - Implement \`FilterConfig::from_args()\` to convert CLI args
   - Add validation methods for encoding and tag names

3. **Filtering Logic** (in string extraction pipeline)
   - Apply \`min-len\` filter during or after extraction
   - Apply encoding filter by skipping unwanted encoding attempts
   - Apply tag filters when assembling final output
   - Ensure filtering preserves ranking/scoring when applicable

4. **Error Handling**
   - Invalid encoding names → clear error message with valid options
   - Invalid tag names → clear error message with valid options
   - Conflicting \`--only-tags\` and \`--notags\` → clap conflict group

### Example Usage

\`\`\`bash
# Extract only URLs and domains with minimum length 10
stringy --only-tags url,domain --min-len 10 malware.exe

# Extract only UTF-16 strings (common in PE files)
stringy --enc utf16le malware.exe

# Extract only tagged/classified strings
stringy --notags suspicious.elf

# Combine filters for precision
stringy --min-len 8 --enc ascii,utf8 --only-tags filepath,registry binary.dll
\`\`\`

## Acceptance Criteria

- [ ] \`--min-len\` argument filters strings by minimum length
- [ ] \`--enc\` argument accepts comma-separated encoding list and filters accordingly
- [ ] \`--only-tags\` argument accepts comma-separated tag list and shows only matching strings
- [ ] \`--notags\` flag excludes untagged strings
- [ ] \`--only-tags\` and \`--notags\` are mutually exclusive (enforced by clap)
- [ ] Invalid encoding names produce helpful error messages
- [ ] Invalid tag names produce helpful error messages
- [ ] Unit tests cover:
  - Argument parsing for all flags
  - Filter configuration validation
  - Filtering logic for each argument type
  - Mutual exclusivity enforcement
  - Edge cases (empty results, no matches, etc.)
- [ ] Documentation updated with filtering examples
- [ ] Filtering works correctly in both human-readable and JSON output modes

## Dependencies

- **Blocked by**: Basic CLI Structure (must be completed first)
- **Depends on**: String extraction and tagging system (framework exists)

## Testing Strategy

1. **Unit Tests** (\`tests/cli_filtering.rs\`):
   - Parse valid and invalid argument combinations
   - Validate filter configuration creation
   - Test filter application logic in isolation

2. **Integration Tests**:
   - Run stringy with various filter combinations on test binaries
   - Verify output contains only expected strings
   - Test edge cases (no matches, all filtered out, etc.)

## Task ID

\`stringy-analyzer/filtering-cli-arguments\`

## Related Issues

- Basic CLI Structure (prerequisite)
- String Extraction Engine (#TBD)
- Semantic Tagging System (#TBD)"

# Add priority:medium label since it's in the MVP milestone
gh issue edit 30 --add-label "priority:medium"

echo "✓ Issue #30 enhanced successfully"

Length of output: 157

---

@unclesp1d3r, I've successfully enhanced issue #30! Here's what was updated:

Title Enhancement

Old: "Filtering CLI Arguments"
New: "Implement CLI Filtering Arguments for String Extraction Control"

The new title is more descriptive and action-oriented, clearly indicating what will be implemented and why.

Body Enhancements

The issue now includes:

1. Overview - Explains the purpose and importance for reverse engineering workflows
2. Context - Real-world use cases for malware analysts and reverse engineers showing why filtering is essential
3. Requirements - References specifications 7.1-7.4
4. Proposed Solution - Detailed technical approach including:
   • All four CLI arguments (--min-len, --enc, --only-tags, --notags)
   • Implementation strategy across multiple modules
   • Error handling approach
   • Example usage patterns
5. Acceptance Criteria - Comprehensive checklist with unit test requirements
6. Dependencies - Clear blocking relationships with other tasks
7. Testing Strategy - Unit and integration test plans
8. Task ID - Preserved original task identifier

Metadata Updates

Labels Added:

• priority:medium - Since this is part of the MVP milestone, it warrants medium priority

Preserved:

• All existing labels (area:analyzer, type:enhancement, status:backlog, lang:rust, needs:tests)
• Assignee: unclesp1d3r
• Milestone: v0.1

The enhanced issue now provides clear implementation guidance with technical details aligned to Rust/clap best practices, making it ready for development work. You can view the updated issue at: #30

🐰✨