Merge pull request #101 from pineapaul/sandbox

Threat Library and MITRE Integration

Author: pineapaul

INFORMATION_ASSETS_LINKING_DOCUMENTATION.md

@@ -0,0 +1,268 @@
+# Information Assets Linking in Threat Library
+
+## Overview
+
+The Threat Library now includes comprehensive linking capabilities with Information Assets, allowing security teams to establish direct relationships between threats and the assets they could potentially impact. This feature enhances risk assessment and provides better visibility into threat exposure across the organization.
+
+## Features
+
+### 1. **Information Assets Column in DataTable**
+- **New Column**: Added "Information Assets" column to the main threats table
+- **Visual Display**: Shows linked assets as green tags with asset names
+- **Tooltip Support**: Hover over tags to see full asset details including category and type
+- **Truncation**: Displays first 2 assets with "+X more" indicator for additional assets
+
+### 2. **Enhanced Add Threat Modal**
+- **Asset Selection**: Users can select multiple information assets when creating custom threats
+- **Checkbox Interface**: Clean, intuitive selection with asset details displayed
+- **Asset Information**: Shows asset name, category, type, and criticality level
+- **Validation**: Ensures proper linking between threats and assets
+
+### 3. **MITRE ATTACK Integration Enhancement**
+- **Two-Step Process**: 
+  1. Select MITRE technique from the framework
+  2. Choose affected information assets
+- **Asset Selection Modal**: Dedicated modal for selecting assets after technique selection
+- **Context Preservation**: Shows selected technique details during asset selection
+- **Streamlined Workflow**: Efficient import process with asset linking
+
+### 4. **Database Schema Updates**
+- **New Field**: Added `informationAssets` array to threats collection
+- **Array Structure**: Contains array of information asset IDs
+- **Backward Compatibility**: Existing threats automatically get empty array
+- **Data Population**: API automatically populates asset details when fetching threats
+
+## Technical Implementation
+
+### Database Schema
+
+```typescript
+interface Threat {
+  // ... existing fields
+  informationAssets: string[] // Array of information asset IDs
+}
+
+interface InformationAsset {
+  id: string
+  informationAsset: string
+  category: string
+  type: string
+  criticality: string
+}
+```
+
+### API Endpoints
+
+#### 1. **GET /api/information-assets/list**
+- **Purpose**: Fetch available information assets for selection
+- **Response**: Simplified asset list with essential fields
+- **Authentication**: Required
+- **Use Case**: Populate asset selection dropdowns
+
+#### 2. **Enhanced POST /api/threats**
+- **New Field**: Accepts `informationAssets` array
+- **Validation**: Ensures array format
+- **Storage**: Stores asset IDs in threats collection
+
+#### 3. **Enhanced GET /api/threats**
+- **Population**: Automatically populates asset details
+- **Performance**: Efficient batch loading of asset information
+- **Response**: Includes full asset objects with threat data
+
+### Frontend Components
+
+#### 1. **Asset Selection Interface**
+- **Checkbox Grid**: Organized asset selection with detailed information
+- **Search & Filter**: Easy asset discovery (future enhancement)
+- **Visual Feedback**: Clear indication of selected assets
+
+#### 2. **Asset Display Components**
+- **Tag System**: Green tags for information assets
+- **Tooltip Integration**: Rich information on hover
+- **Responsive Design**: Adapts to different screen sizes
+
+#### 3. **Modal Workflow**
+- **Add Threat Modal**: Integrated asset selection
+- **MITRE Import Modal**: Two-step asset selection process
+- **State Management**: Proper form state handling
+
+## Usage Instructions
+
+### Creating Custom Threats with Asset Linking
+
+1. **Open Add Threat Modal**
+   - Click "Add Threat" button
+   - Fill in threat details (name, description, category, severity)
+
+2. **Select Information Assets**
+   - Scroll to "Information Assets" section
+   - Check boxes for affected assets
+   - See asset details (name, category, type, criticality)
+
+3. **Complete Threat Creation**
+   - Add tags and other metadata
+   - Click "Add Threat" to save
+
+### Importing MITRE Techniques with Asset Linking
+
+1. **Open MITRE Import Modal**
+   - Click "Import from MITRE" button
+   - Use filters to find relevant techniques
+
+2. **Select Technique**
+   - Click "Select Assets" button on desired technique
+   - Review technique details in confirmation modal
+
+3. **Choose Affected Assets**
+   - Select information assets from the list
+   - Review selections and asset details
+
+4. **Complete Import**
+   - Click "Import Threat" to create threat with asset links
+
+### Viewing Asset Links
+
+1. **Main Table View**
+   - See linked assets as green tags in "Information Assets" column
+   - Hover over tags for detailed information
+
+2. **Export Functionality**
+   - CSV export includes asset information
+   - Asset names separated by semicolons
+
+## Migration and Setup
+
+### Database Migration
+
+Run the migration script to update existing threats:
+
+```bash
+npm run migrate-threats
+```
+
+This script:
+- Adds `informationAssets` field to existing threats
+- Sets default value as empty array
+- Maintains data integrity
+- Provides migration verification
+
+### Verification Steps
+
+1. **Check Migration Results**
+   - Verify all threats have `informationAssets` field
+   - Confirm field is properly initialized as empty array
+
+2. **Test Asset Linking**
+   - Create new threat with asset selection
+   - Import MITRE technique with asset linking
+   - Verify links appear in main table
+
+3. **Validate Data Display**
+   - Check asset tags render correctly
+   - Verify tooltip information
+   - Test CSV export functionality
+
+## Future Enhancements
+
+### 1. **Advanced Asset Filtering**
+- **Search Functionality**: Find assets by name, category, or type
+- **Criticality Filtering**: Filter by asset criticality level
+- **Department Grouping**: Organize assets by business unit
+
+### 2. **Bulk Operations**
+- **Mass Asset Linking**: Link multiple threats to assets simultaneously
+- **Asset Impact Analysis**: View all threats affecting specific assets
+- **Risk Scoring**: Calculate risk scores based on asset criticality
+
+### 3. **Reporting and Analytics**
+- **Asset Exposure Reports**: Identify most vulnerable assets
+- **Threat Distribution**: Analyze threat patterns across asset types
+- **Risk Heat Maps**: Visual representation of asset-threat relationships
+
+### 4. **Integration Features**
+- **Asset Management Systems**: Sync with external asset databases
+- **Risk Management Tools**: Export data for risk assessment platforms
+- **Compliance Reporting**: Generate compliance reports with asset context
+
+## Security Considerations
+
+### 1. **Access Control**
+- **Authentication Required**: All asset operations require valid session
+- **Authorization Checks**: Users can only access authorized assets
+- **Audit Logging**: Track asset selection and modification
+
+### 2. **Data Validation**
+- **Input Sanitization**: Prevent injection attacks
+- **Asset ID Validation**: Ensure valid asset references
+- **Array Size Limits**: Prevent excessive asset linking
+
+### 3. **Privacy Protection**
+- **Asset Information**: Display only necessary asset details
+- **User Permissions**: Respect asset access restrictions
+- **Data Encryption**: Secure asset data in transit and storage
+
+## Troubleshooting
+
+### Common Issues
+
+#### 1. **Assets Not Loading**
+- Check database connection
+- Verify information-assets collection exists
+- Check user authentication status
+
+#### 2. **Asset Selection Not Working**
+- Verify JavaScript console for errors
+- Check form state management
+- Ensure proper event handling
+
+#### 3. **Migration Failures**
+- Verify MongoDB connection string
+- Check database permissions
+- Review migration script logs
+
+### Debug Steps
+
+1. **Check Browser Console**
+   - Look for JavaScript errors
+   - Verify API responses
+   - Check network requests
+
+2. **Verify Database State**
+   - Confirm threats collection structure
+   - Check information-assets collection
+   - Validate data relationships
+
+3. **Test API Endpoints**
+   - Verify authentication
+   - Check response formats
+   - Validate error handling
+
+## Support and Maintenance
+
+### Regular Maintenance
+
+1. **Data Validation**
+   - Periodic checks for orphaned asset references
+   - Validation of asset-threat relationships
+   - Cleanup of invalid links
+
+2. **Performance Monitoring**
+   - Monitor API response times
+   - Check database query performance
+   - Optimize asset population queries
+
+3. **User Training**
+   - Provide guidance on asset selection
+   - Explain linking best practices
+   - Document workflow procedures
+
+### Contact Information
+
+For technical support or feature requests:
+- **Development Team**: Submit issues through project repository
+- **Documentation**: Refer to this document and related guides
+- **Training**: Contact security team for user training sessions
+
+---
+
+*This documentation covers the Information Assets Linking feature as implemented in the Threat Library. For additional information or support, please refer to the main project documentation or contact the development team.*