{"id":30722664,"url":"https://github.com/locksec/odsf","last_synced_at":"2025-09-03T11:10:20.824Z","repository":{"id":304884835,"uuid":"1020422258","full_name":"locksec/odsf","owner":"locksec","description":"OSINT Defense and Security Framework (ODSF)","archived":false,"fork":false,"pushed_at":"2025-07-16T16:11:59.000Z","size":368,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-16T19:37:03.161Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/locksec.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-15T21:03:28.000Z","updated_at":"2025-07-16T16:12:03.000Z","dependencies_parsed_at":"2025-07-17T01:37:42.907Z","dependency_job_id":"573ccc5e-a3da-4bae-80c5-464e047c6895","html_url":"https://github.com/locksec/odsf","commit_stats":null,"previous_names":["locksec/odsf"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/locksec/odsf","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/locksec%2Fodsf","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/locksec%2Fodsf/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/locksec%2Fodsf/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/locksec%2Fodsf/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/locksec","download_url":"https://codeload.github.com/locksec/odsf/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/locksec%2Fodsf/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273431495,"owners_count":25104513,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-03T02:00:09.631Z","response_time":76,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-09-03T11:10:16.983Z","updated_at":"2025-09-03T11:10:20.808Z","avatar_url":"https://github.com/locksec.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ODSF Build Tool\n\nA build tool for generating a static HTML page for the OSINT Defense \u0026 Security Framework (ODSF). The project uses a Node.js build script that transforms JSON framework data into a modern, interactive HTML documentation page with custom CSS and JavaScript.\n\n## Commands\n\n### Build the ODSF HTML page\n```bash\nnpm run build\n```\nor\n```bash\nnode build-odsf.js\n```\n\nThis command:\n- Automatically finds and reads the latest framework JSON file (e.g., `odsf-framework-v0.1.2.json`)\n- Creates an `output/` directory with all generated files\n- Generates a static HTML file at `output/index.html`\n- Generates CSS file at `output/css/odsf-styles.css`\n- Copies JavaScript file to `output/js/odsf-script.js`\n- Copies all favicon files (favicon.ico, PNG icons, SVG, web manifest)\n- Validates JSON structure and shows warnings/errors\n- Outputs build statistics to the console\n- Uses configuration from `.odsf-config.json` if present (see Configuration section)\n- Minification is enabled by default (configurable via .odsf-config.json)\n\n### Build with minification\n```bash\nnpm run build:minify\n```\nor\n```bash\nnode build-odsf.js --minify\n```\n\nForces minification of HTML, CSS and JavaScript files regardless of configuration.\n\n### Watch mode for development\n```bash\nnpm run watch\n```\nor\n```bash\nnode build-odsf.js --watch\n```\n\nWatches for changes in source files and automatically rebuilds. Press Ctrl+C to exit.\n\n### Clean the output directory\n```bash\nnpm run clean\n```\n\nRemoves the entire output directory and its contents.\n\n## Architecture\n\n### Data Flow\n1. **Input**: Latest `odsf-framework-v*.json` file - Automatically detected based on version number\n2. **Process**: `build-odsf.js` - Transforms JSON data into HTML using templates and external CSS/JavaScript\n3. **Output** (all in `output/` directory): \n   - `output/index.html` - Main HTML page with custom CSS\n   - `output/css/odsf-styles.css` - Copied CSS styles with dark/light theme support\n   - `output/js/odsf-script.js` - Copied JavaScript functionality\n\n### Key Components\n\n**build-odsf.js** - Main build script that:\n- Uses ES modules syntax (`import`/`export`)\n- Automatically finds the latest framework JSON file by version\n- Creates output directory structure (`output/`, `output/css/`, `output/js/`)\n- Uses external templates from `src/templates/` directory\n- Validates JSON structure before processing\n- Comprehensive error handling with detailed error messages\n- Copies all files from `src/favicon/` to output root\n- Supports command-line flags: `--watch`, `--minify`, `--no-minify`\n- Implements utility functions:\n  - `validateFramework()` - Validates JSON structure and shows warnings/errors\n  - `findLatestFrameworkFile()` - Locates the highest version JSON file\n  - `readTemplate()` - Reads template files from the templates directory\n  - `replaceVariables()` - Replaces template variables with actual data\n  - `escapeHtml()` - Sanitizes text content\n\n**build-utils.js** - Utility module that provides:\n- `minifyCSS()` - Simple CSS minification without external dependencies\n- `minifyJS()` - Basic JavaScript minification preserving functionality\n- `minifyHTML()` - HTML minification removing comments and unnecessary whitespace\n- `loadConfig()` - Loads and merges configuration from `.odsf-config.json`\n\n**Template System** - Uses separate template files for better maintainability:\n- `src/templates/index.html` - Main HTML structure\n- `src/templates/partials/header.html` - Header section with hero content\n- `src/templates/partials/stats.html` - Statistics display\n- `src/templates/partials/main-content.html` - Main content wrapper\n- `src/templates/partials/focus-area.html` - Focus area template\n- `src/templates/partials/subcategory.html` - Subcategory template\n- `src/templates/partials/control.html` - Control template\n- `src/templates/partials/footer.html` - Footer with copyright and license\n\n**src/scripts/main.js** - Enhanced interactivity including:\n- Advanced search with real-time filtering and highlighting\n- Search covers all text including descriptions, business rationale, and implementation guidance\n- Auto-expands implementation guidance when search matches\n- Clear search button (X) inside the search bar\n- Focus area filter buttons (tile layout) with toggle functionality\n- All On/All Off buttons for focus area filters\n- Expand All/Collapse All buttons for content\n- Breadcrumb navigation showing \"Focus Areas\" \u003e current view\n- Quick jump modal (Ctrl+K) with keyboard navigation\n- Light/Dark theme toggle with localStorage persistence\n- Keyboard shortcuts:\n  - Ctrl/Cmd+F: Focus search\n  - Ctrl/Cmd+K: Open quick jump modal\n  - Ctrl/Cmd+E: Toggle expand/collapse all\n  - ESC: Close modals or clear search\n  - Arrow keys: Navigate in quick jump modal\n- All focus areas enabled by default\n- Focus areas start collapsed by default\n- Statistics counters animate from 0 to final value on page load\n\n**src/styles/main.css** - Custom styles including:\n- Dark theme (default) with light theme support\n- CSS variables for easy theming\n- Fluid typography system using CSS clamp()\n- Custom color scheme with cyan (#40d0d5) and red (#ea3232) accents\n- Focus area tile buttons with grid layout\n- Focus area expansion animations with rotating chevrons\n- Search highlighting without padding\n- Statistics section with glassmorphism effect and animated counters\n- Quick jump modal with glassmorphism effect\n- Keyboard shortcuts bar with glassmorphism effect (bottom right)\n- Header buttons: Contributors (opens modal), About (external link), License (opens modal)\n- Version badge on separate line with semi-transparent cyan styling\n- Light mode uses dark gray text instead of black\n- Theme toggle button (top right)\n- Print-ready styles that expand all sections\n- Footer with copyright notice and license button\n- License modal with detailed commercial/non-commercial terms\n- Contributors modal showing primary author and contributors (dynamically loaded from JSON)\n\n### Expected JSON Structure\n\nThe `odsf-framework-v*.json` file should contain:\n```json\n{\n  \"framework_name\": \"string\",\n  \"framework_version\": \"string\",\n  \"framework_version_desc\": \"string\", // Optional: version description\n  \"author\": \"string\",\n  \"contributors\": \"string\", // Optional: comma-separated list or array\n  \"description\": \"string\",\n  \"focus_areas\": [\n    {\n      \"id\": \"string\",\n      \"name\": \"string\",\n      \"description\": \"string\",\n      \"business_rationale\": \"string\",\n      \"scope\": \"string\",\n      \"alignment\": {\n        \"nist_csf\": [\"string\"],\n        \"iso_27001\": [\"string\"]\n      },\n      \"subcategories\": [\n        {\n          \"id\": \"string\",\n          \"name\": \"string\",\n          \"objective\": \"string\",\n          \"controls\": [\n            {\n              \"id\": \"string\",\n              \"name\": \"string\",\n              \"description\": \"string\",\n              \"implementation_guidance\": [\"string\"]\n            }\n          ]\n        }\n      ]\n    }\n  ]\n}\n```\n\n## Configuration\n\nThe build tool supports configuration via `.odsf-config.json` file in the project root. See `.odsf-config.example.json` for reference.\n\n**Default behavior**: The `npm run build` command automatically uses `.odsf-config.json` if it exists. With the current configuration file, minification is enabled by default for all file types.\n\n### Configuration Options\n\n```json\n{\n  \"minify\": {\n    \"enabled\": true,     // Enable minification by default\n    \"css\": true,         // Minify CSS files\n    \"js\": false,         // JavaScript minification disabled (to preserve functionality)\n    \"html\": true         // Minify HTML output\n  },\n  \"watch\": {\n    \"debounce\": 300      // Milliseconds to wait before rebuilding in watch mode\n  }\n}\n```\n\n### Command-line Flag Precedence\n\n- `--minify` forces minification regardless of config\n- `--no-minify` disables minification regardless of config\n- Without flags, uses configuration file settings\n\n## Important Notes\n\n- **JSON File Detection**: The build script automatically finds and uses the latest version of `odsf-framework-v*.json` files in the directory\n- **ES Modules**: The project uses modern ES modules syntax with `\"type\": \"module\"` in package.json\n- **No Dependencies**: This is a standalone script with no external npm dependencies - uses only Node.js built-in modules (fs, path, url)\n- **Source Files**: Project structure follows web development best practices:\n  - `build-odsf.js` - Main build script\n  - `build-utils.js` - Utility functions for minification and config\n  - `src/templates/` - HTML template files\n  - `src/styles/main.css` - Source CSS styles\n  - `src/scripts/main.js` - Source JavaScript functionality\n  - `.odsf-config.json` - Build configuration (minification enabled by default)\n  - `.odsf-config.example.json` - Example configuration file\n- **Output Files**: The build generates all files in the `output/` directory:\n  - `output/index.html` - Main HTML page (optionally minified)\n  - `output/css/odsf-styles.css` - CSS styles (optionally minified)\n  - `output/js/odsf-script.js` - JavaScript functionality (optionally minified)\n  - All files in the output directory form a self-contained website\n\n## UI Features\n\n- **Modern Design**: Professional dark theme design with cyan/red accent colors\n- **Theme Support**: Light/dark mode toggle with localStorage persistence\n- **Typography**: Jost font family with fluid typography using CSS clamp()\n- **Hero Section**: Large \"MINIMIZE WHAT CAN BE KNOWN\" tagline with badges\n- **Badges**: Version, Contributors, and About (links to psysecure.com/odsf)\n- **Statistics**: Modern glassmorphism cards with icons and counting animations\n- **Content Width**: Maximum 1200px width for comfortable reading\n- **Search**: \n  - Real-time filtering with highlighting (no padding on highlights)\n  - Searches all content including descriptions and business rationale\n  - Clear button (X) inside search bar\n  - Auto-expands implementation guidance when matched\n- **Filtering**: \n  - Focus area buttons in tile layout (full width, grid)\n  - All On/All Off buttons on the left\n  - Independent toggle functionality for each area\n  - All areas enabled by default\n- **Navigation**: \n  - Breadcrumb trail\n  - Quick jump modal (Ctrl+K) with arrow key navigation\n  - Keyboard shortcuts bar with glassmorphism effect\n- **Content Display**:\n  - Each focus area shows Description and Business Rationale sections\n  - Expandable sections (collapsed by default)\n  - Expand All/Collapse All buttons on the right\n- **Responsive**: \n  - Fluid typography and layouts\n  - Quick jump sidebar hidden on mobile\n  - Keyboard shortcuts hidden on mobile\n- **Print-ready**: Automatically expands all sections when printing\n- **Favicon Support**: Multiple favicon formats including SVG and web manifest\n\n## Current Implementation Status\n\nThe ODSF build tool is fully functional with all core features implemented:\n- ✅ Static site generation from JSON data\n- ✅ Modern, responsive UI with dark/light themes\n- ✅ Advanced search with highlighting\n- ✅ Focus area filtering with tile buttons\n- ✅ Quick jump navigation\n- ✅ Keyboard shortcuts\n- ✅ Favicon support\n- ✅ Print-ready output\n- ✅ Self-contained output (no external dependencies)\n- ✅ JSON schema validation with empty array warnings\n- ✅ Comprehensive error handling for all file operations\n- ✅ Clean command to remove output directory\n- ✅ Watch mode for automatic rebuilds during development\n- ✅ HTML, CSS and JavaScript minification with configurable options\n- ✅ Configuration file support (.odsf-config.json)\n- ✅ Dynamic author/contributors display from JSON data\n- ✅ Footer with copyright notice (CC BY-NC-SA 4.0)\n- ✅ License modal with commercial/non-commercial terms\n- ✅ Contributors modal with primary author and contributors\n\n## GitHub Pages Deployment (Secure Method)\n\nDeploy your ODSF site to GitHub Pages while keeping your framework JSON file private.\n\n### Important Security Note\n\nSince the framework JSON file contains proprietary data and is excluded from the repository (in `.gitignore`), we cannot use GitHub Actions to build the site. Instead, we build locally and deploy only the output files.\n\n### Deployment Workflow\n\n1. **Build locally** with your private JSON file:\n   ```bash\n   npm run build\n   ```\n\n2. **Deploy to GitHub Pages**:\n   ```bash\n   npm run deploy\n   ```\n\nThe deployment script (`deploy-output-only.sh`):\n- Builds the site locally using your private JSON file\n- Creates a temporary directory for deployment (doesn't affect your working directory)\n- Initializes a fresh git repository in that temp directory\n- Copies only the output files (HTML, CSS, JS, favicons)\n- Creates/updates the `gh-pages` branch with ONLY the output files\n- Your JSON file is never committed or exposed\n- Automatically includes CNAME file for custom domain\n- Cleans up the temp directory when done\n\n### Initial Setup\n\n1. **Configure GitHub Pages**:\n   - Go to repository Settings → Pages\n   - Source: Deploy from a branch\n   - Branch: `gh-pages` (will be created by first deployment)\n   - Folder: `/ (root)`\n   - Custom domain: `odsf.psysecure.com`\n   - Enforce HTTPS: ✓ (checked)\n\n2. **Set up DNS** (at your domain provider):\n   ```\n   CNAME odsf.psysecure.com -\u003e [username].github.io\n   ```\n\n### Security Benefits\n\n- ✅ Framework JSON file remains completely private\n- ✅ Only compiled output is public\n- ✅ Source code and build process stay in your private main branch\n- ✅ Public can access the framework documentation but not the raw data\n\n### Update Process\n\nTo update your site:\n1. Make changes to your JSON file or templates\n2. Test locally: `npm run build`\n3. Deploy updates: `npm run deploy`\n\n### Alternative: Private Repository\n\nIf you have GitHub Pro/Team/Enterprise, you can:\n1. Keep the entire repository private\n2. Use GitHub Actions with the JSON file\n3. Still host public GitHub Pages from the private repo\n\nBut with a free account, the manual deployment approach keeps your data secure.\n\n### Troubleshooting\n\n**If files go missing after deployment:**\n- The deployment script now works in a separate directory and won't affect your project files\n- Your JSON file should never be deleted (it's in .gitignore)\n\n**If deployment fails:**\n- Ensure your JSON file exists: `odsf-framework-v*.json`\n- Check that you're in the project root (where package.json is)\n- Verify git remote is set: `git remote -v`\n\n**Important files to backup:**\n- Your framework JSON file (`odsf-framework-v*.json`)\n- Any custom modifications to templates\n\n## License\n\nThis build tool is MIT licensed. The ODSF framework content is licensed separately under CC BY-NC-SA 4.0.\n\n## Live Demo\n\nVisit [odsf.psysecure.com](https://odsf.psysecure.com) to see the framework in action.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flocksec%2Fodsf","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flocksec%2Fodsf","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flocksec%2Fodsf/lists"}