User Stories - opnDossier#

Overview#

This document captures user stories for the opnDossier CLI tool in EARS (Easy Approach to Requirements Syntax) format. Each story follows the pattern:

As a [user type] I want [capability] So that [benefit] Given [precondition] When [action] Then [expected outcome]

Table of Contents#

[TOC]

Core Functionality Stories#

XML Parsing and Validation#

US-001 As a network security operator I want to parse OPNsense XML configuration files So that I can analyze firewall configurations offline Given I have a valid OPNsense config.xml file When I run the opnDossier command with the XML file Then the system should parse the XML structure and validate it against the OPNsense schema

US-002 As a security auditor I want meaningful error messages for malformed XML files So that I can quickly identify and fix configuration issues Given I have an invalid or corrupted config.xml file When I attempt to parse the file Then the system should provide specific error messages with line/column information

Markdown Conversion#

US-003 As a network administrator I want XML configurations converted to structured Markdown format So that I can generate human-readable documentation Given I have a parsed OPNsense configuration When I request markdown conversion Then the system should generate well-formatted markdown with hierarchy preservation

US-004 As a DevOps engineer I want syntax highlighting in the terminal output So that I can easily read and understand configuration details Given I have converted configuration data When I view the output in the terminal Then the system should display colored, syntax-highlighted markdown using Charm Lipgloss

File Export#

US-005 As a documentation team member I want to export processed configurations to markdown files So that I can save documentation for later reference Given I have processed a configuration file When I specify an output file path Then the system should save the markdown documentation to the specified location

US-006 As a security professional I want to specify custom output directories So that I can organize documentation according to my workflow Given I want to save documentation to a specific location When I provide a custom output path Then the system should create the directory if needed and save the file there

Offline Operation#

US-007 As a security operator in an airgapped environment I want the tool to operate completely offline So that I can use it in isolated network environments Given I have no internet connectivity When I run any opnDossier command Then the system should function without external dependencies or network calls

US-008 As a compliance auditor I want zero external dependencies So that I can trust the tool in high-security environments Given I'm working in a restricted environment When I deploy and run opnDossier Then the system should not require any external services or APIs

CLI Interface#

US-009 As a network administrator I want an intuitive command-line interface So that I can quickly process configuration files Given I have the opnDossier tool installed When I run the command with appropriate arguments Then the system should provide clear feedback and process my request

US-010 As a new user I want comprehensive help documentation So that I can learn how to use the tool effectively Given I'm unfamiliar with the tool When I run the help command or use --help flag Then the system should display detailed usage instructions and examples

US-011 As a experienced operator I want verbose and quiet output modes So that I can control the level of detail in output Given I'm running the tool in different contexts When I use --verbose or --quiet flags Then the system should adjust output detail accordingly

Configuration Management#

US-012 As a security professional I want to manage settings via YAML configuration files So that I can customize the tool behavior for my environment Given I have specific preferences for tool behavior When I create a configuration file Then the system should load and apply my settings automatically

US-013 As a operator in a team environment I want to use environment variables for sensitive options So that I can avoid hardcoding sensitive information Given I need to configure sensitive settings When I set environment variables with OPNDOSSIER_ prefix Then the system should use those values while keeping them secure

US-014 As a power user I want to override configuration with command-line flags So that I can make temporary changes without modifying config files Given I have a configuration file with default settings When I provide command-line flags Then the system should prioritize flags over all other configuration sources (highest precedence)

Performance Requirements#

US-015 As a operator processing large configurations I want efficient memory usage during XML processing So that I can handle large firewall configurations Given I have a large config.xml file When I process the file Then the system should use streaming XML processing to minimize memory usage

US-016 As a operator requiring quick feedback I want fast CLI startup times So that I can work efficiently in time-sensitive situations Given I need to process multiple configurations quickly When I start the opnDossier command Then the system should start up quickly for operator efficiency

US-017 As a operator handling multiple files I want concurrent processing capabilities So that I can process multiple files efficiently Given I have multiple configuration files to process When I run concurrent operations Then the system should use goroutines and channels for efficient I/O operations

Error Handling and Recovery#

US-018 As a operator encountering errors I want clear, actionable error messages So that I can quickly resolve issues and continue working Given an error occurs during processing When the system encounters the error Then it should provide specific, actionable error messages

US-019 As a operator working with complex configurations I want graceful error recovery So that I can continue processing even if some parts fail Given a configuration has some invalid sections When I process the configuration Then the system should handle errors gracefully and continue processing valid sections

Testing and Validation#

US-020 As a developer I want comprehensive test coverage So that I can trust the tool's reliability Given I'm developing or modifying the tool When I run the test suite Then the system should maintain >80% test coverage

US-021 As a operator I want the tool to be thoroughly tested So that I can rely on it in production environments Given I'm using the tool in a critical environment When I run any command Then the system should behave predictably based on comprehensive testing

Documentation and Help#

US-022 As a new user I want clear installation instructions So that I can quickly get started with the tool Given I want to install opnDossier When I follow the installation instructions Then I should have a working installation

US-023 As a operator I want usage examples for common workflows So that I can learn best practices quickly Given I'm learning to use the tool When I review the documentation Then I should find clear examples for common use cases

US-024 As a team lead I want comprehensive API documentation So that my team can understand and extend the tool Given I need to integrate or extend the tool When I review the API documentation Then I should find clear interface definitions and usage examples

Security and Compliance#

US-025 As a security professional I want no telemetry or external communication So that I can use the tool in sensitive environments Given I'm working with sensitive configurations When I use the tool Then it should not transmit any data externally

US-026 As a compliance auditor I want secure error messages So that sensitive information is not exposed Given an error occurs during processing When the system reports the error Then it should not expose sensitive configuration details

US-027 As a security operator I want input validation for all user inputs So that I can trust the tool with any configuration file Given I provide input to the tool When the system processes the input Then it should validate all inputs comprehensively

Cross-Platform Support#

US-028 As a operator on different platforms I want the tool to work on Linux, macOS, and Windows So that I can use it in any environment Given I'm working on different operating systems When I install and run opnDossier Then it should work consistently across all supported platforms

US-029 As a operator in containerized environments I want the tool to work in containers So that I can integrate it into my deployment pipeline Given I'm running the tool in a container When I execute opnDossier commands Then it should function properly in the containerized environment

Build and Distribution#

US-030 As a operator I want easy installation from package managers So that I can quickly deploy the tool Given I need to install opnDossier When I use my system's package manager Then I should be able to install it easily

US-031 As a security professional I want signed and verified binaries So that I can trust the integrity of the tool Given I'm downloading the tool When I verify the binary Then it should have proper signatures and checksums

US-032 As a operator in restricted environments I want static binaries with no runtime dependencies So that I can deploy it easily in any environment Given I need to deploy the tool When I copy the binary Then it should run without requiring additional runtime dependencies

Development and Maintenance#

US-033 As a developer I want automated quality checks So that I can maintain code quality Given I'm making changes to the codebase When I commit my changes Then automated checks should validate code quality

US-034 As a maintainer I want automated release management So that I can focus on development rather than release tasks Given I need to create a new release When I trigger the release process Then it should automatically build, test, and distribute the release

US-035 As a contributor I want clear contributing guidelines So that I can contribute effectively to the project Given I want to contribute to the project When I follow the contributing guidelines Then my contributions should meet project standards

Monitoring and Observability#

US-036 As a operator I want structured logging So that I can troubleshoot issues effectively Given I encounter an issue with the tool When I review the logs Then I should find structured, searchable log entries

US-037 As a operator I want performance profiling capabilities So that I can optimize the tool for my use case Given I need to understand performance characteristics When I enable profiling Then the system should provide detailed performance information

US-038 As a operator I want health check capabilities So that I can verify the tool is working correctly Given I want to verify the tool's status When I run a health check command Then the system should report its operational status

Non-Functional Requirements#

Performance Stories#

US-039 As a operator processing large files I want individual tests to complete in under 100ms So that I can get quick feedback during development Given I'm running the test suite When I execute individual tests Then each test should complete in less than 100ms

US-040 As a operator I want memory-efficient processing So that I can handle large configuration files Given I have a large config.xml file When I process the file Then the system should use streaming processing to minimize memory usage

Security Stories#

US-041 As a security professional I want no hardcoded secrets So that I can trust the tool in sensitive environments Given I'm reviewing the codebase When I search for sensitive information Then I should not find any hardcoded secrets

US-042 As a operator I want secure defaults So that I can use the tool safely without additional configuration Given I'm using the tool for the first time When I run commands without custom configuration Then the system should use secure default settings

Usability Stories#

US-043 As a operator I want support for both light and dark terminal themes So that I can use the tool comfortably in any environment Given I'm using different terminal themes When I run opnDossier commands Then the output should be readable in both light and dark themes

US-044 As a operator I want consistent output formatting So that I can rely on predictable output Given I'm using the tool across different terminal environments When I run the same command Then the output should be consistently formatted

US-045 As a operator I want tab completion support So that I can work more efficiently Given I'm using a shell that supports tab completion When I use tab completion Then the system should provide appropriate completions for commands and options

US-046 As a red team operator I want to generate a recon report from a config.xml file So that I can identify potential attack surfaces, misconfigurations, and pivot paths during an engagement Given I have a valid OPNsense config.xml file When I run the opnDossier command analyze with the --mode=red flag Then the system should generate a recon report highlighting WAN-exposed services, weak NAT rules, admin portals, and known attack surfaces

Status: Deferred to v2.1 (see #174).

US-047 As a blue team engineer I want to generate a defensive audit of an OPNsense config So that I can quickly identify misconfigurations, insecure defaults, and missed hygiene steps Given I have a valid OPNsense config.xml file When I run the opnDossier command analyze with the --mode=blue flag Then the system should generate a defensive audit report with audit findings, structured configuration tables, and recommendations with severity ratings

Status: Deferred to v2.1 (see #174).

US-048 As an infrastructure maintainer or auditor I want to generate a complete but neutral summary of a config file So that I can include it in documentation or audit records without red/blue-specific commentary Given I have a valid OPNsense config.xml file When I run the opnDossier command analyze with the --mode=standard flag Then the system should generate a detailed but neutral config documentation report including system metadata, rule counts, interfaces, certs, DHCP, routes, and HA

Status: Removed — standard audit mode was removed. Neutral documentation is handled by the convert command.

Acceptance Criteria#

Core Functionality Acceptance#

• XML parsing works with valid OPNsense config.xml files
• Invalid XML files produce meaningful error messages
• Markdown conversion preserves configuration hierarchy
• Terminal output includes syntax highlighting
• File export creates valid markdown files
• Tool operates completely offline
• CLI provides comprehensive help documentation
• Configuration management supports YAML files and environment variables
• Command-line flags override configuration file settings
• Performance meets specified requirements (<100ms for tests, efficient memory usage)
• Analyze command with --mode=red generates recon reports highlighting WAN-exposed services, weak NAT rules, admin portals, and known attack surfaces (deferred to v2.1; see #174)
• Analyze command with --mode=blue generates defensive audits with audit findings, structured configuration tables, and recommendations with severity ratings (deferred to v2.1; see #174)
• Analyze command with --mode=standard generates detailed but neutral config documentation Removed — standard audit mode was removed; neutral documentation is handled by the convert command.
• Analyze command validates --mode flag values and provides clear error messages for invalid modes
• Analyze command output format is consistent across all modes and includes appropriate security context
• Red team reports include snarky or attacker-focused commentary when --blackhat-mode is enabled
• Blue team reports include structured configuration tables for visibility and actionable recommendations
• Standard reports provide comprehensive, neutral documentation suitable for audit records Removed — handled by convert command.

Quality Assurance Acceptance#

• Test coverage exceeds 80%
• All linting checks pass
• Code follows Google Go Style Guide
• Documentation is complete and accurate
• Cross-platform compatibility is verified
• Security requirements are met (no telemetry, secure defaults)
• Performance benchmarks are established and met
• Error handling is comprehensive and user-friendly

Deployment Acceptance#

• Multi-platform binaries are available
• Package manager support is implemented
• Release process is automated
• Binary signatures and checksums are provided
• Installation instructions are clear and complete
• Container support is verified
• Static compilation works correctly

Story Mapping#

Epic: Core Functionality#

• XML Parsing and Validation
• Markdown Conversion
• File Export
• CLI Interface
• Audit Report Generation

Epic: Configuration Management#

• YAML Configuration Files
• Environment Variables
• Command-line Overrides

Epic: Quality and Reliability#

• Testing and Validation
• Error Handling
• Performance Optimization

Epic: Security and Compliance#

• Offline Operation
• Secure Defaults
• Input Validation

Epic: User Experience#

• Documentation and Help
• Cross-platform Support
• Accessibility

Epic: Development and Maintenance#

• Build and Distribution
• Monitoring and Observability
• Contributing Guidelines

This document should be updated as requirements evolve and new user needs are identified.