Standards Domain
Types and operations for security standards processing, validation, and mapping to CWE. Supports multiple frameworks like NIST, ISO, COBIT, and custom standards.
Standards Results
ci.transparency.cwe.types.standards.results
Standards domain result types and operations using composition.
Immutable dataclasses for tracking standards loading, validation, and mapping analysis operations. Built using composition of base building blocks for clean separation of concerns.
Core types
- StandardsLoadingResult: Tracks standards definition loading with framework detection
- StandardsValidationResult: Tracks standards validation with field and constraint checks
- StandardsMappingResult: Tracks standards mapping validation and analysis
Key operations
- add_standard: Add successfully loaded standards definition
- validate_standard: Validate standards data with field checks
- analyze_mappings: Analyze standards mappings for consistency
Design principles
- Immutable: uses dataclasses.replace for all modifications
- Composition-based: uses base building blocks for reusable functionality
- Standards-specific: tailored for standards definition requirements and patterns
- Type-safe: follows Python 3.12+ and pyright strict conventions
__all__ = ['StandardsLoadingResult', 'StandardsValidationResult', 'StandardsMappingResult', 'StandardsMappingDict', 'StandardsControlDict', 'StandardsItemDict', 'StandardsDataDict', 'ValidationResultsDict', 'ValidationDetailsDict', 'SeverityCountsDict', 'MappingResultsDict', 'MappingTypesDict', 'ErrorSummaryDict', 'LoadingSummaryDict', 'ValidationSummaryDict', 'MappingSummaryDict', 'FrameworkCollection', 'add_standard', 'track_invalid_standards_file', 'track_skipped_standards_file', 'validate_standard', 'validate_standards_field', 'batch_validate_standards', 'analyze_mappings', 'add_mapping', 'get_standards_loading_summary', 'get_standards_validation_summary', 'get_mapping_summary']
module-attribute
ErrorSummaryDict = dict[str, Any]
LoadingSummaryDict = dict[str, Any]
MappingResultsDict = dict[str, list[str]]
MappingSummaryDict = dict[str, Any]
MappingTypesDict = dict[str, int]
SeverityCountsDict = dict[str, int]
StandardsDataDict = dict[str, StandardsItemDict]
ValidationDetailsDict = dict[str, list[str]]
ValidationResultsDict = dict[str, bool]
ValidationSummaryDict = dict[str, Any]
DuplicateCollection
dataclass
Tracks duplicate IDs and their associated file paths.
Attributes
duplicate_ids : dict[str, list[Path]] Dictionary mapping duplicate IDs to lists of file paths where duplicates were found.
duplicate_count
property
Return the number of duplicate IDs tracked in the collection.
Returns
int The number of duplicate IDs.
has_duplicates
property
Return True if there are any duplicate IDs, otherwise False.
FileCollection
dataclass
Tracks processed, failed, and skipped files.
Attributes
processed_files : list[Path] list of files that have been processed. failed_files : list[Path] list of files that failed to process. skipped_files : list[Path] list of files that were skipped.
failed_file_count
property
Return the number of failed files.
processed_file_count
property
Return the number of processed files.
skipped_file_count
property
Return the number of skipped files.
total_files
property
Return the total number of files (processed, failed, skipped).
FrameworkCollection
dataclass
Tracks statistics for frameworks.
Could be reused for any domain that categorizes by framework.
framework_count
property
Return the number of frameworks tracked.
most_common_framework
property
Return the most common framework based on highest count.
add_framework(framework)
Add or increment a framework count.
LoadingCounts
dataclass
Tracks the number of successfully loaded and failed items.
Attributes
loaded_count : int Number of items successfully loaded. failed_count : int Number of items that failed to load.
is_successful
property
Return True if there are no failed validations, otherwise False.
success_rate
property
Return the rate of successful loads as a float between 0 and 1.
total_attempted
property
Return the total number of attempted loads (successful + failed).
MessageCollection
dataclass
Collects error, warning, and info messages.
Attributes
errors : list[str] list of error messages. warnings : list[str] list of warning messages. infos : list[str] list of informational messages.
error_count
property
Return the number of error messages.
has_errors
property
Return True if there are any error messages, otherwise False.
has_warnings
property
Return True if there are any warning messages, otherwise False.
info_count
property
Return the number of informational messages.
total_messages
property
Return the total number of messages (errors, warnings, infos).
warning_count
property
Return the number of warning messages.
ReferenceCollection
dataclass
Tracks references between items and their validity.
Could be reused for any domain that has inter-item references.
has_invalid_references
property
True if there are invalid references.
has_orphaned_items
property
True if there are orphaned items.
invalid_reference_count
property
Number of invalid references.
orphaned_item_count
property
Number of items with no references.
total_references_count
property
Total number of references tracked.
add_invalid_reference(reference_desc)
Add an invalid reference.
add_orphaned_item(item_id)
Add an orphaned item.
add_reference(from_item, to_item)
Add a reference between items.
StandardsControlDict
Bases: TypedDict
Typed structure for standards control data.
StandardsItemDict
Bases: TypedDict
Typed structure for standards data.
StandardsLoadingResult
dataclass
Represents the result of loading standards data using composition.
Composes base building blocks for clean separation of concerns.
Attributes
standards : StandardsDataDict Dictionary of loaded standards data. loading : LoadingCounts Statistics about loading success and failures. messages : MessageCollection Collection of error, warning, and info messages. files : FileCollection Tracking of processed, failed, and skipped files. frameworks : FrameworkCollection Statistics for frameworks encountered. duplicates : DuplicateCollection Tracking of duplicate IDs and their associated files. _format_breakdown : dict[str, int] Tracks format usage breakdown.
is_successful
property
Return True if loading is successful and there are no error messages.
loaded_standard_ids
property
All loaded standard IDs (sorted for stable output).
standards_count
property
Return the number of standards loaded.
add_error(msg)
Add error message (added by decorator).
add_format_info(format_version)
Track format usage.
add_info(msg)
Add info message (added by decorator).
add_warning(msg)
Add warning message (added by decorator).
get_control_count()
Get total number of controls across all standards.
get_standard(standard_id)
Get standards data by ID.
get_standards_by_framework(framework)
Return all standards loaded for a given framework.
Parameters
framework : str The framework name to filter standards by.
Returns
StandardsDataDict Dictionary of standards data filtered by the specified framework.
has_standard(standard_id)
Check if a standards ID was loaded.
StandardsMappingDict
Bases: TypedDict
Typed structure for standards mapping data.
StandardsMappingResult
dataclass
Result from standards mapping validation and analysis using composition.
Tracks standards mapping consistency, invalid references detection, and mapping statistics analysis.
Attributes
validation : ValidationCounts Statistics about mapping validation. messages : MessageCollection Collection of error, warning, and info messages. references : ReferenceCollection Tracking of references between standards and targets. mapping_results : MappingResultsDict Mapping of standards IDs to their target IDs. mapping_types : MappingTypesDict Count of mapping types. duplicate_mappings : list[str] Duplicate mappings detected.
duplicate_mapping_count
property
Number of duplicate mappings detected.
has_duplicate_mappings
property
True if duplicate mappings were detected.
is_successful
property
Return True if mapping analysis is successful.
total_mappings_count
property
Total number of mappings tracked.
add_error(msg)
Add error message (added by decorator).
add_info(msg)
Add info message (added by decorator).
add_warning(msg)
Add warning message (added by decorator).
get_mapping_coverage_rate()
Calculate mapping coverage rate.
get_mappings(standard_id)
Get all mappings for a specific standard.
StandardsValidationResult
dataclass
Represents the result of validating standards data using composition.
Attributes
validation_results : ValidationResultsDict Dictionary of validation results for each standards item. validation : ValidationCounts Statistics about validation success and failures. messages : MessageCollection Collection of error, warning, and info messages. field_errors : list[str] Field-level validation errors. validation_details : ValidationDetailsDict Detailed validation errors per standard. severity_counts : SeverityCountsDict Count of issues by severity level. control_validation_count : int Number of controls validated.
field_error_count
property
Number of field-level validation errors.
has_field_errors
property
True if any field-level validation errors occurred.
is_successful
property
Return True if validation is successful and there are no error messages.
validated_count
property
Return the number of items that have been validated.
validation_rate
property
Validation success rate (0.0 to 1.0).
add_error(msg)
Add error message (added by decorator).
add_info(msg)
Add info message (added by decorator).
add_warning(msg)
Add warning message (added by decorator).
get_failed_standards()
Get list of standards IDs that failed validation.
get_passed_standards()
Get list of standards IDs that passed validation.
get_validation_errors(standard_id)
Get validation errors for a specific standard.
ValidationCounts
dataclass
Tracks the number of passed and failed validations.
Attributes
passed_count : int Number of items that passed validation. failed_count : int Number of items that failed validation.
is_successful
property
Return True if there are no failed validations, otherwise False.
pass_rate
property
Return the rate of passed validations as a float between 0 and 1.
total_validated
property
Return the total number of validated items (passed + failed).
_add_duplicate(duplicates, item_id, file_path)
Add a duplicate ID with its file path.
_add_failed_file(files, file_path)
Add a failed file.
_add_framework(frameworks, framework)
Add or increment a framework count.
_add_message(messages, level, message)
Add a message to the message collection.
_add_processed_file(files, file_path)
Add a processed file.
_add_skipped_file(files, file_path)
Add a skipped file.
_collect_control_mappings(standard_id, control, *, valid_targets, mapping_types, invalid_mappings, orphaned_controls)
Collect target ids from a single control, updating counters and issues.
_extract_control_id(control, unknown_index)
Return a string control id or a stable 'unknown-{n}' fallback.
_increment_loading_counts(counts, *, succeeded=0, failed=0)
Increment loading counts.
_increment_validation_counts(counts, *, passed=0, failed=0)
Increment validation counts.
_process_standard_mappings(standard_id, standards_data, valid_targets, mapping_types, invalid_mappings, orphaned_controls)
Process mappings for a single standard.
add_mapping(result, standard_id, target_id, mapping_type='mapped')
Add a mapping between a standard and target.
add_standard(result, standard_id, standards_data, *, file_path=None)
Add successfully loaded standards to the result.
analyze_mappings(result, standards_dict, valid_targets=None)
Analyze standards mappings for consistency and detect issues.
batch_validate_standards(result, standards_dict)
Validate multiple standards in batch.
get_mapping_summary(result)
Generate standards mapping summary.
get_standards_loading_summary(result)
Generate standards loading summary.
get_standards_validation_summary(result)
Generate standards validation summary.
track_invalid_standards_file(result, file_path, reason)
Track an invalid standards file.
track_skipped_standards_file(result, file_path, reason)
Track a skipped standards file.
validate_standard(result, standard_id, standards_data)
Validate a standards definition with comprehensive field validation.
validate_standards_field(result, standard_id, field_path, field_value, validation_rule)
Validate a specific standards field.
with_message_methods(cls)
Add message methods to result classes.
Decorator that adds add_error(), add_warning(), and add_info() methods to any result class with a MessageCollection field.
options: showsource: false show_signature: true group_by_category: true filters: - "!^"
Standards Errors
ci.transparency.cwe.types.standards.errors
Standards domain error types using enhanced base classes.
Domain-specific error hierarchy for standards operations. Each error inherits from exactly one enhanced base error class and leverages the flexible context system for standards-specific information.
Design principles
- Single inheritance: each error extends exactly one base error class
- Context-rich: uses the flexible context system for standards details
- Consistent: maintains uniform error formatting across all errors
- Minimal: leverages base class functionality rather than duplicating code
Usage patterns
- File operations → FileError, LoadingError, ParsingError
- Validation operations → ValidationError
- Processing operations → OperationError
- General operations → BaseTransparencyError
Typical usage
from ci.transparency.cwe.types.standards import StandardsValidationError
raise StandardsValidationError( "Field validation failed", item_id="NIST-SP-800-53", field_path="controls[0].id", validation_rule="required_field", file_path="nist.yaml" )
Output: "Field validation failed | Item: NIST-SP-800-53 | Field: controls[0].id | Rule: required_field | File: nist.yaml"
__all__ = ['StandardsConfigurationError', 'StandardsConstraintViolationError', 'StandardsDuplicateMappingError', 'StandardsFieldValidationError', 'StandardsFileNotFoundError', 'StandardsFormatError', 'StandardsIntegrityError', 'StandardsInvalidFormatError', 'StandardsInvalidMappingError', 'StandardsLoadingError', 'StandardsMappingError', 'StandardsMissingFieldError', 'StandardsParsingError', 'StandardsProcessingError', 'StandardsValidationError']
module-attribute
BaseTransparencyError
Bases: Exception
Enhanced base exception for all transparency operations.
Provides flexible context tracking for common error patterns without requiring all errors to specify every possible context field.
get_context_parts()
Get contextual information parts for error formatting.
Returns context in order of importance: 1. Operation identification (phase, operation, stage) 2. Progress information (processed/total counts) 3. Resource information (timeouts, limits) 4. File/item context 5. Validation context 6. Error flow context (abort reason, error code)
Returns:
| Type | Description |
|---|---|
list[str]
|
List of context strings (e.g., ["Phase: validation", "Progress: 150/500"]) |
FileError
Bases: BaseTransparencyError
Base exception for file-based operations.
Convenient base for file loading, parsing, and other file-related errors.
LoadingError
OperationError
Bases: BaseTransparencyError
Base exception for operations with progress tracking.
Convenient base for batch processing, phase validation, and other operations that process multiple items with progress tracking.
ParsingError
StandardsConfigurationError
StandardsConstraintViolationError
StandardsDuplicateMappingError
StandardsFieldValidationError
StandardsFileNotFoundError
StandardsFormatError
StandardsIntegrityError
StandardsInvalidFormatError
StandardsInvalidMappingError
StandardsLoadingError
StandardsMappingError
StandardsMissingFieldError
StandardsParsingError
StandardsProcessingError
StandardsValidationError
ValidationError
Bases: BaseTransparencyError
Base exception for validation operations.
Convenient base for schema validation, rule checking, and other validation-related errors.
options: showsource: false show_signature: true group_by_category: true filters: - "!^"