From 1573557164c1af6b7a75b47c4c8387afc4cdf245 Mon Sep 17 00:00:00 2001 From: overcuriousity Date: Wed, 16 Jul 2025 09:10:39 +0200 Subject: [PATCH] readme --- README.md | 373 ++++++++++++++++-------------------------------------- 1 file changed, 108 insertions(+), 265 deletions(-) diff --git a/README.md b/README.md index a1a0927..4610b0f 100644 --- a/README.md +++ b/README.md @@ -1,297 +1,140 @@ -# cc24-hub +# CC24-Hub -Der neue Hub für CC24. Ein Framework für diverse Forensik-Tools und Übersicht über die verfügbaren Anwendungen auf der Plattform. -DISCLAIMER: Vibe-Coding von Anthropic Claude 4 Sonnet. +Ein kuratiertes Verzeichnis für digitale Forensik- und Incident-Response-Tools, entwickelt für die Seminargruppe CC24-w1. -## Features +## 🎯 Projektübersicht -- **Performance**: Sub-2 second load times, sub-500ms filtering -- **YAML-Driven Content**: Easy tool management through simple file edits -- **Dark/Light Themes**: Automatic system detection with manual override -- **Service Monitoring**: Real-time status via Uptime Kuma integration -- **Mobile Responsive**: Works on all device sizes -- **Zero Dependencies**: No external CDNs or cloud services +CC24-Hub ist eine statische Website, die eine strukturierte Übersicht über bewährte DFIR-Tools bietet. Das Projekt orientiert sich am NIST-Framework (SP 800-86) und kategorisiert Tools nach forensischen Domänen und Untersuchungsphasen. -## Quick Start +### Hauptfunktionen -### Prerequisites +- **Tool-Katalog**: Umfassende Sammlung von Open-Source und kommerziellen Forensik-Tools +- **Matrix-Ansicht**: Visualisierung der Tools nach Domänen und Prozess-Phasen +- **Erweiterte Filterung**: Suche nach Name, Beschreibung, Tags, Domäne und Phase +- **Self-Hosted Integration**: Direkte Links zu gehosteten Tool-Instanzen +- **Status-Monitoring**: Live-Überwachung der verfügbaren Services +- **Responsive Design**: Optimiert für Desktop und Mobile +- **Dark/Light Mode**: Automatische Theme-Erkennung mit manueller Überschreibung -- Node.js 16+ -- npm or yarn +## 🛠️ Technischer Stack -### Installation +- **Framework**: [Astro](https://astro.build/) (Static Site Generator) +- **Styling**: Vanilla CSS mit CSS Custom Properties +- **Datenformat**: YAML für Tool-Definitionen +- **Deployment**: Statische HTML-Generierung +- **Node.js**: >=18.0.0 -1. **Clone the repository** - ```bash - git clone https://git.cc24.dev/mstoeck3/cc24-hub - cd cc24-hub - ``` +## 🚀 Installation & Deployment -2. **Install dependencies** - ```bash - npm install - ``` +### Lokale Entwicklung -3. **Start development server** - ```bash - npm start - ``` +```bash +# Repository klonen +git clone https://git.cc24.dev/mstoeck3/cc24-hub.git +cd cc24-hub -4. **Build for production** - ```bash - npm run build - ``` +# Dependencies installieren +npm install -The site will be available at `http://localhost:8080` and files will be generated in `_site/`. +# Development Server starten +npm run dev +``` -## Project Structure +Die Seite ist dann unter `http://localhost:4321` verfügbar. + +### Produktions-Deployment + +```bash +# Build erstellen +npm install && npm run build +``` + +Die statische Seite wird im `dist/` Verzeichnis generiert und kann in die Webroot des Webservers kopiert werden. + +### Verfügbare Scripts + +- `npm run dev` - Development Server +- `npm run build` - Produktions-Build +- `npm run preview` - Vorschau des Builds +- `npm run deploy:static` - Statisches Deployment (Script) + +## 📁 Projektstruktur ``` -dfir-tools-hub/ +cc24-hub/ ├── src/ -│ ├── _data/ # YAML data files -│ │ ├── tools.yaml # Tools database -│ │ └── services.yaml # Service monitoring config -│ ├── _includes/ # Shared template components -│ ├── _layouts/ # Page layout templates -│ │ └── base.njk # Base layout -│ ├── js/ # Client-side JavaScript -│ │ ├── search.js # Search and filtering -│ │ ├── theme.js # Theme management -│ │ ├── modal.js # Tool detail modal -│ │ └── status.js # Status page logic -│ ├── scss/ # Sass stylesheets -│ │ └── main.scss # Main stylesheet -│ ├── about/ -│ │ └── index.njk # About page -│ ├── privacy/ -│ │ └── index.njk # Privacy page -│ ├── status/ -│ │ └── index.njk # Status page -│ └── index.njk # Home page -├── .eleventy.js # Eleventy configuration -├── package.json # Dependencies and scripts -└── README.md # This file +│ ├── components/ # Astro-Komponenten +│ │ ├── Navigation.astro +│ │ ├── ToolCard.astro +│ │ ├── ToolFilters.astro +│ │ └── ToolMatrix.astro +│ ├── data/ +│ │ └── tools.yaml # Tool-Definitionen +│ ├── layouts/ +│ │ └── BaseLayout.astro +│ ├── pages/ # Seiten-Routing +│ │ ├── index.astro +│ │ ├── about.astro +│ │ ├── status.astro +│ │ └── impressum.astro +│ ├── scripts/ +│ │ └── theme.js # Theme-Management +│ └── styles/ +│ └── global.css # Globale Styles +├── public/ # Statische Assets +└── astro.config.mjs # Astro-Konfiguration ``` -## Content Management +## 🔧 Tool-Datenformat -### Adding Tools - -Edit `src/_data/tools.yaml` to add or modify tools: +Tools werden in `src/data/tools.yaml` definiert: ```yaml tools: - - id: new-tool # Unique identifier - name: "Tool Name" # Display name - description: "Brief description of the tool" - domains: # Forensic domains - - "Filesystem Forensics" - - "Network Forensics" - phases: # DFIR phases - - "Datensammlung" - - "Analyse" - platforms: # Supported platforms - - "Linux" - - "Windows" - - "macOS" - skillLevel: "Intermediate" # Beginner|Intermediate|Advanced - accessType: "CLI" # CLI|GUI|Web|SaaS - url: "https://example.com" # Project homepage - tags: # Search tags - - "tag1" - - "tag2" - type: "FOSS" # FOSS|SaaS + - name: "Tool Name" + description: "Beschreibung des Tools" + domains: ["incident-response", "malware-analysis"] + phases: ["data-collection", "analysis"] + platforms: ["Linux", "Windows"] + skillLevel: "intermediate" + accessType: "download" + url: "https://example.com" + projectUrl: "https://hosted.example.com" # Optional für gehostete Tools + license: "Apache 2.0" + tags: ["tag1", "tag2"] + statusUrl: "https://status.example.com/badge" # Optional ``` -### Configuring Services +### Verfügbare Kategorien -Edit `src/_data/services.yaml` for service monitoring: +**Domänen:** +- `incident-response` - Incident Response & Breach-Untersuchung +- `law-enforcement` - Strafverfolgung & Kriminalermittlung +- `malware-analysis` - Malware-Analyse & Reverse Engineering +- `fraud-investigation` - Betrugs- & Finanzkriminalität +- `network-forensics` - Netzwerk-Forensik & Traffic-Analyse +- `mobile-forensics` - Mobile Geräte & App-Forensik +- `cloud-forensics` - Cloud & Virtuelle Umgebungen +- `ics-forensics` - Industrielle Kontrollsysteme (ICS/SCADA) -```yaml -# Uptime Kuma Configuration -uptimeKuma: - enabled: true # Enable/disable integration - apiUrl: "https://status.lab.local/api" - apiKey: "your-api-key" # Optional API key - refreshInterval: 30000 # Refresh every 30 seconds +**Phasen:** +- `data-collection` - Datensammlung +- `examination` - Auswertung +- `analysis` - Analyse +- `reporting` - Bericht & Präsentation +- `collaboration` - Übergreifend & Kollaboration -# Static service definitions -services: - - id: service-id - name: "Service Name" - description: "Service description" - url: "https://service.lab.local" - category: "Analyse Tools" - status: "operational" # operational|degraded|maintenance|down - uptime: "99.9%" - responseTime: "245ms" -``` +## 🤝 Beitragen -## DFIR Methodology +### Tool hinzufügen -Tools are organized according to the standard DFIR framework: +1. Fork des Repositories erstellen +2. Neuen Tool-Eintrag in `src/data/tools.yaml` hinzufügen +3. Pull Request mit Beschreibung der Änderungen erstellen -### Domains -- **Filesystem Forensics**: File system Analyse and recovery -- **Network Forensics**: Network traffic and protocol Analyse -- **Memory Forensics**: RAM and memory artifact Analyse -- **Live Forensics**: Real-time system Analyse -- **Malware Analyse**: Malicious software Auswertung -- **Cryptocurrency**: Blockchain and crypto investigations +### Korrekturen & Verbesserungen -### Phases -- **Datensammlung**: Evidence acquisition and preservation -- **Auswertung**: Data extraction and parsing -- **Analyse**: Evidence correlation and interpretation -- **Bericht & Präsentation**: Documentation and timeline creation - -## Service Status Integration - -### Uptime Kuma Setup - -1. **Install Uptime Kuma** on your network - -2. **Configure monitors** for your DFIR services - -3. **Enable API access** in Uptime Kuma settings - -4. **Update configuration** in `src/_data/services.yaml`: - ```yaml - uptimeKuma: - enabled: true - apiUrl: "https://your-uptime-kuma.local/api" - apiKey: "your-api-key" - ``` - -## Development - -### Available Scripts - -- `npm start` - Start development server with live reload -- `npm run build` - Build production site -- `npm run debug` - Build with debug information -- `npm run clean` - Clean build directory - -### Customization - -#### Themes -- Modify color variables in `src/scss/main.scss` -- Supports CSS custom properties for dynamic theming -- Automatic dark mode detection with manual override - -#### Search and Filtering -- Client-side search for instant results -- Multi-criteria filtering (domain + phase + search term) -- Matrix view for comprehensive tool overview - -#### Performance Optimization -- Static site generation for fast loading -- Minimal JavaScript footprint -- Local asset bundling (no CDNs) -- Optimized CSS with utility classes - -## Deployment - -### Static Hosting - -Build and deploy to any static host: - -```bash -npm run build -# Upload _site/ contents to your web server -``` - -### Docker - -Create a `Dockerfile`: - -```dockerfile -FROM node:18-alpine AS builder -WORKDIR /app -COPY package*.json ./ -RUN npm ci -COPY . . -RUN npm run build - -FROM nginx:alpine -COPY --from=builder /app/_site /usr/share/nginx/html -EXPOSE 80 -``` - -### Self-Hosted Services - -For lab environments, consider deploying alongside: - -- **Timesketch**: Timeline Analyse platform -- **MISP**: Threat intelligence sharing -- **Neo4j**: Graph database for relationships - -## Browser Support - -Features gracefully degrade in older browsers. - -## Contributing - -### Tool Submissions - -1. Fork the repository -2. Add tool information to `src/_data/tools.yaml` -3. Test locally with `npm start` -4. Submit a pull request - -### Issue Bericht & Präsentation - -Report bugs or suggest features via GitHub Issues. - -### Development Guidelines - -- Maintain sub-500ms search performance -- Test across major browsers -- Follow existing code style -- Update documentation for changes - -## License - -BSD-3-Clause License - see LICENSE file for details. - -## Acknowledgments - -- NIST SP 800-86 for DFIR methodology framework -- Eleventy static site generator -- Uptime Kuma for service monitoring -- Open source DFIR community - -## Troubleshooting - -### Common Issues - -**Build fails with Sass errors** -```bash -npm install --save-dev sass@latest -``` - -**Search not working** -- Check browser console for JavaScript errors -- Ensure `window.toolsData` is populated -- Verify YAML syntax in tools.yaml - -**Uptime Kuma integration failing** -- Check network connectivity to API endpoint -- Verify API key permissions -- Review browser network tab for CORS issues - -**Performance issues** -- Ensure tools.yaml isn't excessively large (>1000 tools) -- Check for JavaScript errors blocking execution -- Verify efficient CSS selectors - -### Getting Help - -1. Check the troubleshooting section above -2. Review GitHub Issues for similar problems -3. Open a new issue with: - - Browser and version - - Error messages - - Steps to reproduce +- Bug Reports und Feature Requests über Issues melden +- Code-Beiträge über Pull Requests willkommen +- Dokumentation und Übersetzungen erwünscht