generated from Labyricorn/labyricorn-project-template
Implement CyberSim-OS Phase 1 MVP simulation environment
This commit is contained in:
@@ -1,213 +1,128 @@
|
||||
# Labyricorn Project Template
|
||||
|
||||
A starter template and baseline structure for projects compatible with
|
||||
[Labyricorn](https://www.labyricorn.com).
|
||||
|
||||
This template provides the required `.labyricorn/` publishing records, assistant
|
||||
guidance files (`AGENTS.md`), devlog structure, and the standalone
|
||||
`devlog_editor.py` management utility for local validation and GUI editing.
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
Projects published on Labyricorn maintain their own exhibition pages and
|
||||
development logs directly inside their Git repositories under the `.labyricorn/`
|
||||
directory. The Labyricorn site importer periodically synchronizes these records
|
||||
as read-only content.
|
||||
|
||||
This template includes:
|
||||
|
||||
- **`.labyricorn/` publishing structure**: Validated Lektor-format records for
|
||||
project identity and development logs.
|
||||
- **`devlog_editor.py`**: Standalone GUI and CLI tool for managing devlog entries,
|
||||
validating publishing contracts, and safely publishing changes.
|
||||
- **`AGENTS.md` instructions**: Scoped assistant instructions at repository root
|
||||
and publishing directories to ensure AI assistants adhere to the publishing
|
||||
contract.
|
||||
- **`.gitignore`**: Configured exclusions for Python environments, caches, and build
|
||||
artifacts.
|
||||
|
||||
---
|
||||
|
||||
## Directory Structure
|
||||
|
||||
```text
|
||||
.
|
||||
├── .gitignore
|
||||
├── .labyricorn/
|
||||
│ ├── AGENTS.md # Assistant instructions for publishing content
|
||||
│ ├── README.md # Publishing structure documentation
|
||||
│ ├── project/
|
||||
│ │ ├── AGENTS.md # Instructions for the project exhibition record
|
||||
│ │ ├── contents.lr # Project identity and exhibition narrative
|
||||
│ │ └── <optional logo> # Project logo (PNG, JPEG, WebP)
|
||||
│ └── devlog/
|
||||
│ ├── AGENTS.md # Instructions for devlog records
|
||||
│ ├── contents.lr # Devlog index record
|
||||
│ └── <entry-slug>/ # (Optional) Devlog entry directories
|
||||
│ ├── contents.lr # Devlog entry record
|
||||
│ └── <optional img> # Entry attachments (PNG, JPEG, WebP)
|
||||
├── AGENTS.md # Assistant instructions for the repository
|
||||
├── devlog_editor.py # Standalone devlog editor & validator
|
||||
├── LICENSE # License file
|
||||
└── README.md # Project documentation
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Getting Started
|
||||
|
||||
### 1. Configure the Project Identity
|
||||
|
||||
Edit `.labyricorn/project/contents.lr` to set your project details:
|
||||
|
||||
```ini
|
||||
_model: project
|
||||
---
|
||||
schema_version: 1
|
||||
---
|
||||
project_id: my-project-id
|
||||
---
|
||||
title: My Project Title
|
||||
---
|
||||
summary:
|
||||
|
||||
A concise summary of the project for listings and cards.
|
||||
---
|
||||
status: active
|
||||
---
|
||||
started: 2026-08-23
|
||||
---
|
||||
author: Author Name
|
||||
---
|
||||
repository_url: https://git.labyricorn.com/Owner/my-project
|
||||
---
|
||||
default_branch: main
|
||||
---
|
||||
tags: python, web, tool
|
||||
---
|
||||
body:
|
||||
|
||||
An exhibition narrative describing the project background, goals, and features.
|
||||
```
|
||||
|
||||
#### Project Fields:
|
||||
- `project_id`: Stable lowercase hyphenated slug (e.g. `my-project`).
|
||||
- `title`: Display title for the project.
|
||||
- `summary`: Short multi-line summary.
|
||||
- `status`: One of `active`, `released`, `maintained`, or `archived`.
|
||||
- `started`: Start date in `YYYY-MM-DD` format.
|
||||
- `author`: Author or organization name.
|
||||
- `repository_url`: Public credential-free HTTPS Git URL.
|
||||
- `default_branch`: Target branch name (e.g. `main`).
|
||||
- `logo`: (Optional) Local filename of an image inside `.labyricorn/project/`.
|
||||
- `tags`: Comma-separated technology or topic labels.
|
||||
- `body`: Markdown narrative of the project.
|
||||
|
||||
### 2. Configure the Devlog Index
|
||||
|
||||
Edit `.labyricorn/devlog/contents.lr` to customize the devlog title and summary:
|
||||
|
||||
```ini
|
||||
_model: devlog
|
||||
---
|
||||
schema_version: 1
|
||||
---
|
||||
title: My Project development log
|
||||
---
|
||||
summary: Milestones and development updates for My Project.
|
||||
```
|
||||
|
||||
### 3. Add Devlog Entries
|
||||
|
||||
To add an entry manually, create a directory under `.labyricorn/devlog/<entry-slug>/`
|
||||
containing `contents.lr`:
|
||||
|
||||
```ini
|
||||
_model: devlog-entry
|
||||
---
|
||||
schema_version: 1
|
||||
---
|
||||
title: Initial Project Milestone
|
||||
---
|
||||
date: 2026-08-23
|
||||
---
|
||||
author: Author Name
|
||||
---
|
||||
summary:
|
||||
|
||||
Overview of the milestone accomplishments.
|
||||
---
|
||||
tags: release, setup
|
||||
---
|
||||
source_commit: <40-character-commit-hash>
|
||||
---
|
||||
body:
|
||||
|
||||
Detailed Markdown description of the milestone, technical decisions, and progress.
|
||||
```
|
||||
|
||||
Alternatively, use `devlog_editor.py` to create and edit entries interactively.
|
||||
|
||||
---
|
||||
|
||||
## Devlog Editor
|
||||
|
||||
The included `devlog_editor.py` script is a standalone utility with zero external
|
||||
dependencies (uses Python standard library and Tkinter).
|
||||
|
||||
### CLI Validation
|
||||
|
||||
Validate all project and devlog records without opening a GUI:
|
||||
|
||||
```bash
|
||||
python devlog_editor.py --validate
|
||||
```
|
||||
|
||||
### Graphical Editor
|
||||
|
||||
Launch the Tkinter management interface to view repository status, draft entries,
|
||||
and publish updates:
|
||||
|
||||
```bash
|
||||
python devlog_editor.py
|
||||
```
|
||||
|
||||
Features of the GUI editor:
|
||||
- **Repository status**: Displays current branch, remote, and ahead/behind counts.
|
||||
- **Entry manager**: Create, edit, and delete devlog entries with automatic slug and date handling.
|
||||
- **Publishing safety**: Stages and commits only `.labyricorn/` publishing files, leaving application source files untouched.
|
||||
|
||||
---
|
||||
|
||||
## Publishing Rules & Constraints
|
||||
|
||||
The Labyricorn site importer enforces strict validation rules on imported repositories:
|
||||
|
||||
1. **Native Lektor Records**: Records must be named `contents.lr` and declare `schema_version: 1`.
|
||||
2. **No Raw HTML**: HTML tags (`<script>`, `<style>`, `<div>`, etc.) are prohibited in text fields and Markdown bodies.
|
||||
3. **Approved Images**: Attachments must be PNG, JPEG, or WebP files located within the record directory. Files must match their magic-byte signatures.
|
||||
4. **Limits**: Up to 100 imported files, maximum 5 MiB per file, and maximum 20 MiB total per project snapshot.
|
||||
5. **Source Commits**: Devlog `source_commit` values must be valid 40-character commit hashes existing on the branch history.
|
||||
6. **No Symlinks or Executables**: Linked paths and executable scripts under `.labyricorn/` are rejected.
|
||||
|
||||
---
|
||||
|
||||
## Assistant Guidance (`AGENTS.md`)
|
||||
|
||||
This repository uses hierarchical `AGENTS.md` files to guide coding assistants:
|
||||
|
||||
- **`AGENTS.md` (Root)**: General project guidelines, authorization boundaries, and devlog practices.
|
||||
- **`.labyricorn/AGENTS.md`**: Publishing boundary contract and security rules.
|
||||
- **`.labyricorn/project/AGENTS.md`**: Rules for editing project exhibition metadata.
|
||||
- **`.labyricorn/devlog/AGENTS.md`**: Standards for crafting verifiable devlog entries.
|
||||
|
||||
Coding assistants working in this repository should always review the nearest
|
||||
applicable `AGENTS.md` before making changes.
|
||||
|
||||
---
|
||||
|
||||
## License
|
||||
|
||||
This template is released into the public domain under the [Unlicense](LICENSE).
|
||||
# CyberSim OS
|
||||
|
||||
**Phase 1 MVP: Scriptable CS End User Teaching Environment with Certificate Verification**
|
||||
|
||||
CyberSim OS is an offline-first, browser-native cybersecurity simulation platform designed for ordinary end users. Learners enter a convincing fictional enterprise desktop, perform routine workplace activities, investigate ambiguous events, encounter realistic threats (credential phishing, malicious attachments) and legitimate false flags, receive a 7-axis behavioral after-action assessment, and earn cryptographically verifiable completion certificates (`*.cybercert`).
|
||||
|
||||
---
|
||||
|
||||
## Key Features
|
||||
|
||||
- **Convincing Fictional Desktop**: Original Windows-like theme with draggable/resizable windows, active/inactive focus states, taskbar, Start launcher, simulation clock, and system toast notifications with audio cues.
|
||||
- **Core Simulated Workplace Applications**:
|
||||
- **Inlook**: Email client with header inspector (RFC sender vs. friendly name), link hover destination tooltips, phishing report workflow, and reply/delete actions.
|
||||
- **Navigator**: Web browser supporting intranet directories, policy hubs, and external spoofed credential-harvesting portals.
|
||||
- **Files**: Virtual filesystem managing Documents, Downloads, and Company Shared folders.
|
||||
- **Doc Viewer**: Lightweight renderer for spreadsheets (`.xlsx`), policies (`.pdf`), and memos.
|
||||
- **Security Center**: Endpoint protection dashboard, real-time alert logs, incident report confirmations, and delayed alert triggers.
|
||||
- **Realistic Decision Model**: Teaches *"Observe → Investigate → Verify → Decide → Act"* rather than *"Strange = Malicious"*. False flags and legitimate urgent notices test discernment.
|
||||
- **Delayed Consequences Engine**: Unsafe actions (e.g. submitting credentials on a phishing page) trigger delayed consequence alerts in Security Center without giving immediate arcade-like game-over feedback.
|
||||
- **7-Axis Behavioral Scoring**:
|
||||
1. *Threat Detection* (20 pts)
|
||||
2. *Investigation & Evidence Gathering* (20 pts)
|
||||
3. *Safe Handling* (15 pts)
|
||||
4. *Independent Verification* (15 pts)
|
||||
5. *Incident Reporting* (15 pts)
|
||||
6. *False Positive Control* (15 pts)
|
||||
7. *Operational Judgment* (Passing threshold: 80 / 100)
|
||||
- **Verifiable Cryptographic Certificates**:
|
||||
- Web Crypto SHA-256 scenario fingerprinting.
|
||||
- Portable, structured `*.cybercert` JSON credential export.
|
||||
- Standalone offline certificate validator (`verify.html`).
|
||||
- **100% Offline-First & Zero Dependencies**: Runs directly from any static web server, GitHub Pages, or the bundled `launcher.py` with zero npm/node/external CDN requirements.
|
||||
|
||||
---
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Option 1: Standalone Local Launcher (Python 3)
|
||||
Run the lightweight local launcher to start the server at `http://127.0.0.1:8080`:
|
||||
|
||||
```bash
|
||||
python launcher.py
|
||||
```
|
||||
|
||||
Your default web browser will open automatically.
|
||||
|
||||
### Option 2: Static Web Server
|
||||
Serve the `src/` directory with any static HTTP server:
|
||||
|
||||
```bash
|
||||
cd src
|
||||
python -m http.server 8000
|
||||
```
|
||||
Open [http://127.0.0.1:8000](http://127.0.0.1:8000) in your browser.
|
||||
|
||||
### Option 3: Direct Static Hosting
|
||||
Host the repository on GitHub Pages or any static file host pointing to `src/index.html`.
|
||||
|
||||
---
|
||||
|
||||
## Certificate Verification
|
||||
|
||||
To verify a `*.cybercert` certificate issued by CyberSim OS:
|
||||
|
||||
1. Open `src/verify.html` in your web browser.
|
||||
2. Drag and drop the `*.cybercert` file into the verification area.
|
||||
3. The offline verifier recalculates the SHA-256 integrity hash, verifies the scenario fingerprint, and confirms the passing score and learner identity.
|
||||
|
||||
---
|
||||
|
||||
## Architecture & Directory Structure
|
||||
|
||||
```
|
||||
CyberSim-OS/
|
||||
├── .labyricorn/ # Labyricorn exhibition & devlog publishing records
|
||||
├── src/
|
||||
│ ├── index.html # Main desktop simulation interface
|
||||
│ ├── verify.html # Standalone offline certificate verifier
|
||||
│ ├── css/
|
||||
│ │ ├── theme-windows.css # Fictional Windows-like enterprise theme tokens
|
||||
│ │ ├── desktop.css # Window manager, taskbar, start menu, tray, toasts
|
||||
│ │ ├── components.css # Modals, form inputs, buttons, badges, tabs
|
||||
│ │ └── apps.css # Inlook, Navigator, Files, DocViewer, SecurityCenter
|
||||
│ ├── js/
|
||||
│ │ ├── main.js # Application bootstrapper & scenario loader
|
||||
│ │ ├── core/
|
||||
│ │ │ ├── window_manager.js# Window lifecycle, stacking, drag, min/max/close
|
||||
│ │ │ ├── desktop.js # Desktop shell, launcher, clock, simulation controls
|
||||
│ │ │ └── notifications.js # Toast notifications & Web Audio synth audio chime
|
||||
│ │ ├── apps/
|
||||
│ │ │ ├── inlook.js # Email client with RFC header/link inspection
|
||||
│ │ │ ├── navigator.js # Simulated browser with intranet & phishing pages
|
||||
│ │ │ ├── files.js # Virtual filesystem explorer
|
||||
│ │ │ ├── docviewer.js # Spreadsheet and document viewer
|
||||
│ │ │ └── security_center.js # Endpoint status & incident report dashboard
|
||||
│ │ ├── engine/
|
||||
│ │ │ ├── event_bus.js # Behavioral telemetry logger
|
||||
│ │ │ └── consequence.js # Delayed consequence scheduler
|
||||
│ │ ├── scenario/
|
||||
│ │ │ ├── scenario_ref1.js # Reference scenario ("NexaCore Shift 1")
|
||||
│ │ │ └── fingerprint.js # Web Crypto SHA-256 scenario fingerprinting
|
||||
│ │ ├── scoring/
|
||||
│ │ │ ├── scorer.js # Multi-axis behavioral scoring engine
|
||||
│ │ │ └── aar.js # After-Action Report modal with pedagogical feedback
|
||||
│ │ └── cert/
|
||||
│ │ ├── cert_generator.js# *.cybercert JSON generator & printable certificate
|
||||
│ │ └── cert_verifier.js # Offline cryptographic certificate verifier
|
||||
│ └── assets/ # Embedded SVG icons and media
|
||||
├── launcher.py # Zero-dependency local 127.0.0.1 web server
|
||||
├── devlog_editor.py # Labyricorn devlog validation & editing tool
|
||||
└── README.md # Project documentation
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Validation & Devlog Maintenance
|
||||
|
||||
Run the validation suite to ensure `.labyricorn/` records and devlog entries adhere to the schema:
|
||||
|
||||
```bash
|
||||
python devlog_editor.py --validate
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## License
|
||||
|
||||
MIT License. See `LICENSE` for details.
|
||||
|
||||
Reference in New Issue
Block a user