
TL;DR
Blackglass_Suite is a safe, offline-first research toolkit for generating synthetic adversary behaviors in isolated testbeds. This guide explains how to use it responsibly to validate detection, logging, and response controls without ever exposing production systems or sensitive data.
Table of Contents
- Introduction
- Who This Is For
- Safety & Legal Prerequisites
- Threat Model & Use Cases
- Quickstart (Offline Lab)
- Architecture Overview
- Example Scenarios & Detection Goals
- Test Plans & Telemetry Collection
- Configuration Templates
- Running the Tool - CLI Examples
- MITRE ATT&CK Coverage
- Troubleshooting
- What's Next
1. Introduction
Many security tools are built and tested in connected environments, but some of the most insidious threats operate where your network sensors are blind: on air-gapped critical systems, isolated industrial/SCADA networks, or in scenarios where an attacker deliberately disconnects a machine.
Blackglass_Suite is a safe, offline-first research toolkit designed to generate synthetic adversary behaviors in isolated testbeds, helping validate detection, logging, and response controls.
Goals:
- Reproduce realistic offline attack techniques in a safe lab
- Ensure tests are reproducible, auditable, and free of sensitive artifacts
- Provide templates for telemetry collection and detection rule development
2. Who This Is For
This toolkit is designed for:
- Blue teams validating detection capabilities in air-gapped environments
- SOC analysts developing and testing detection rules for offline scenarios
- Security researchers studying offline attack patterns and defensive gaps
- Incident responders building air-gap compromise playbooks
- Security engineers validating EDR and logging coverage without network dependencies
This is NOT for anyone without explicit authorization to test target systems.
3. Safety & Legal Prerequisites
⚠️ AUTHORIZED TESTING ONLY - ISOLATED ENVIRONMENTS REQUIRED ⚠️
Do not run this on production or any environment you do not own or have explicit written permission to test.
Before any test:
- Obtain written authorization (scope, systems, time window, rollback plan)
- Isolate the test systems (air-gapped network segment or separate lab VLAN)
- Use disposable VMs/snapshots for all exercises
- Strip or synthesize any credentials, secrets, or real personal data
- Keep a public-safe audit trail
- Verify snapshot/backup functionality before running any module
- Document rollback procedures and test them before live runs
4. Threat Model & Use Cases
Blackglass_Suite emulates offline-first attacker behaviors:
- USB / removable-media initial access
- Lateral movement via SMB or local privilege escalation without internet callbacks
- Data staging and exfiltration simulation to removable storage
- Persistence mechanisms that do not require network C2
- Credential harvesting (simulated, non-destructive enumeration)
Use cases: Validate EDR detection coverage, verify host-based logging, test incident response playbooks, develop detection rules for MITRE ATT&CK techniques in offline contexts, and train SOC analysts.
5. Quickstart (Offline Lab)
Safe Testing Workflow
Step 1: Obtain written authorization
Step 2: Isolate test environment
Step 3: Create VM snapshot
Step 4: Configure telemetry
Step 5: Run module in safe mode
Step 6: Collect & analyze
Step 7: Restore snapshot
Quick commands (lab machine):
git clone https://github.com/GnomeMan4201/Blackglass_Suite.git
cd Blackglass_Suite
less README.md
less SAFE_RUNNING.md
Create snapshot before every run:
# libvirt
virsh snapshot-create-as --domain target-vm pretest-snapshot
# VirtualBox
VBoxManage snapshot "target-vm" take "pretest-snapshot"
# VMware
vmrun snapshot "/path/to/vm.vmx" "pretest-snapshot"
6. Architecture Overview
Directory Structure:
core/
— orchestration scripts and runners
modules/
— modular scenario implementations (synthetic & safe)
labs/
— lab playbooks and VM definitions for local, offline hypervisor deployments
docs/
— documentation, safe-run guides, detection mapping
telemetry/
— telemetry collection scripts and parsers
detection-rules/
— example detection rules
Supported Hypervisors: libvirt/KVM, VirtualBox, VMware Workstation/Fusion
7. Example Scenarios & Detection Goals
USB-based local execution chain
Steps simulated:
- User plugs removable drive (simulated)
- Script executes local binary (non-destructive enumeration)
- Binary writes staging file to attached volume
Detection goals: Host process events, file creation on removable media, offline telemetry validation (MITRE ATT&CK: T1091, T1005)
Local privilege escalation (simulated)
Steps: Execute simulated escalation, create child process with elevated token, access sensitive paths.
Detection goals: Process anomaly detection, file access monitoring (MITRE ATT&CK: T1068)
8. Test Plans & Telemetry Collection
Linux telemetry:
collectors:
- type: sysmon-linux
enabled: true
- type: auditd
rules:
- "-w /tmp -p wa -k testwrites"
- "-w /mnt/usb -p rwxa -k usb_access"
Windows telemetry:
<Sysmon schemaversion="4.90">
<EventFiltering>
<ProcessCreate onmatch="include">
<ParentImage condition="contains">removable</ParentImage>
</ProcessCreate>
</EventFiltering>
</Sysmon>
9. Configuration Templates
Module config template:
module:
id: usb_local_exec
description: "Simulated local execution chain from attached removable media."
safe_mode: true
mitre_attack: [T1091, T1204]
actions:
- mount_image: "sim_usb.img"
- execute: "sim_bin --enumerate --output /tmp/stage.json"
Detection rule template (Sigma-style):
title: Blackglass USB Local Exec Simulation Detection
id: bg-usb-001
description: Detects executable creation on removable volumes
logsource:
product: windows
service: sysmon
detection:
selection:
EventID: 1
Image|contains: '\removable\'
condition: selection
level: medium
tags: [attack.t1091, blackglass_simulation]
10. Running the Tool - CLI Examples
# List modules
./bgctl list-modules
# Show module details
./bgctl info usb_local_exec
# Dry-run
./bgctl run usb_local_exec --dry-run --output ./runs/run1.json
# Safe-mode with snapshot
./bgctl run usb_local_exec --safe-mode --collect-telemetry ./telemetry --snapshot-before
# Restore snapshot
./bgctl snapshot-restore --vm target-vm --snapshot pretest-snapshot
11. MITRE ATT&CK Coverage
Technique | Name | Module(s) |
T1091 | Replication Through Removable Media | usb_local_exec |
T1005 | Data from Local System | usb_local_exec, credential_enum_sim |
T1068 | Exploitation for Privilege Escalation | local_priv_escalation |
T1021.002 | Remote Services: SMB | smb_lateral_sim |
12. Troubleshooting
- Module fails → Check safe_mode, snapshot, hypervisor API
- No telemetry → Verify collector permissions & paths
- Snapshot restore fails → Confirm names, API access, disk space
- Detection rules not firing → Validate telemetry and rule syntax
13. What's Next
Upcoming features include:
- Extended MITRE ATT&CK coverage with more offline technique simulations
- Automated report generation with comprehensive telemetry analysis
- Integration with SIEM platforms (Splunk, Elastic)
- Pre-built lab templates for common scenarios
- Growing detection rule library
Final Notes
Blackglass_Suite is designed for defensive security research only. Always obtain proper authorization, work in isolated environments, document your testing procedures, share findings responsibly, and respect ethical boundaries. The goal is to make defenders better at detecting offline threats and improve overall security posture.