DEV Community

Cover image for The Ghost in the Machine: A Defender's Guide to Offline Security Testing with Blackglass_Suite
GnomeMan4201
GnomeMan4201

Posted on

The Ghost in the Machine: A Defender's Guide to Offline Security Testing with Blackglass_Suite

#security #cybersecurity #devops

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

  1. Introduction
  2. Who This Is For
  3. Safety & Legal Prerequisites
  4. Threat Model & Use Cases
  5. Quickstart (Offline Lab)
  6. Architecture Overview
  7. Example Scenarios & Detection Goals
  8. Test Plans & Telemetry Collection
  9. Configuration Templates
  10. Running the Tool - CLI Examples
  11. MITRE ATT&CK Coverage
  12. Reporting & Remediation Checklist
  13. Troubleshooting
  14. Contributing & Repo Hygiene
  15. Appendix: Sample Configs
  16. What's Next
  17. Get Involved

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. How do you know your EDR, your host logging, and your IR playbooks will hold up when there's no cloud to call home to?

Blackglass_Suite is a safe, offline-first research toolkit designed to answer that question by 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.

Goals:

  • Reproduce realistic offline attack techniques in a safe lab.
  • Ensure tests are reproducible, auditable, and free of sensitive artifacts.
  • Provide straightforward 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 and exercising 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

All techniques are intentionally synthetic, non-destructive.

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 completely separate lab VLAN)
  • Use disposable VMs/snapshots for all exercises
  • Strip or synthesize any credentials, secrets, or real personal data from test artifacts
  • Keep a public-safe audit trail: test plan, operator identity, telemetry endpoints, and retention policy
  • 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 attacker behaviors that are offline-first:

  • USB / removable-media initial access (malicious payload execution simulation)
  • 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 for local execution chains
  • Verify host-based logging (Sysmon, auditd) and log ingestion pipelines
  • Test incident response playbooks for air-gapped compromise scenarios
  • Develop detection rules for MITRE ATT&CK techniques in offline contexts
  • Train SOC analysts on telemetry analysis without network indicators

5. Quickstart (Offline Lab)

Safe Testing Workflow

**Step 1: Obtain Authorization** Get written permission with defined scope, systems, time window, and rollback plan **Step 2: Isolate Test Environment** Set up air-gapped network segment or separate lab VLAN **Step 3: Create VM Snapshot** Create pre-test snapshot for quick rollback capability **Step 4: Configure Telemetry** Enable Sysmon, auditd, and collection endpoints **Step 5: Run Module in Safe Mode** Execute synthetic attack scenario with safeguards enabled **Step 6: Collect & Analyze** Gather telemetry and validate detection rules **Step 7: Restore Snapshot** Return system to clean state for next test

This quickstart assumes a local lab with a host acting as the target and an analysis host that collects telemetry.

Assumptions

  • You have local filesystem access and a VM hypervisor (VirtualBox/VMware/Libvirt)
  • You will clone Blackglass_Suite into an isolated lab workstation
  • You will not connect the lab hosts to production networks
  • Your hypervisor supports snapshots (see docs/HYPERVISOR_SETUP.md for configuration)

Quick commands (lab machine):

# Clone the repository (replace with actual repo URL)
git clone https://github.com/GnomeMan4201/Blackglass_Suite.git
cd Blackglass_Suite

# Inspect documentation
less README.md
less SAFE_RUNNING.md
less docs/HYPERVISOR_SETUP.md
Enter fullscreen mode Exit fullscreen mode

Create snapshot before every run (example per hypervisor):

# libvirt
virsh snapshot-create-as --domain target-vm pretest-snapshot "pretest snapshot"

# VirtualBox
VBoxManage snapshot "target-vm" take "pretest-snapshot"

# VMware
vmrun snapshot "/path/to/vm.vmx" "pretest-snapshot"
Enter fullscreen mode Exit fullscreen mode

6. Architecture Overview

core/
Orchestration scripts and main runners 		modules/
Modular attack scenarios 		labs/
VM definitions & playbooks
telemetry/
Collection scripts & parsers 		detection-rules/
Example detection rules 		docs/
Documentation & guides

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
  • tests/ — unit/integration tests
  • telemetry/ — telemetry collection scripts and parsers
  • detection-rules/ — example detection rules

Supported Hypervisors: libvirt/KVM, VirtualBox, VMware Workstation/Fusion

See docs/HYPERVISOR_SETUP.md for detailed configuration instructions.

7. Example Scenarios & Detection Goals

USB-based local execution chain

USB Mount
T1091 → Execute Binary
T1204 → Enumerate
T1005 → Stage Data
T1074

Steps simulated

  1. User plugs removable drive (simulated)
  2. Script executes local binary (non-destructive enumeration)
  3. Binary writes staging file to attached volume

Detection goals

  • Host process events (Sysmon/auditd)
  • File creation on removable media
  • Offline telemetry validation
  • MITRE ATT&CK: T1091, T1005

Local privilege escalation (simulated)

Steps simulated

  1. Execute simulated escalation
  2. Create child process with elevated token (simulated)
  3. Access sensitive paths (logged)

Detection goals

  • Process anomaly detection
  • File access monitoring
  • MITRE ATT&CK: T1068

8. Test Plans & Telemetry Collection

Telemetry Collection Flow

Target System
Running module → Collectors
Sysmon/auditd → Storage
Local logs → Analysis
Detection rules

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"
      - "-a exit,always -F arch=b64 -S execve -k exec_tracking"
  - type: process_accounting
    enabled: true
  - type: file_integrity
    paths:
      - /mnt/usb
      - /tmp
Enter fullscreen mode Exit fullscreen mode

Windows telemetry

<Sysmon schemaversion="4.90">
  <EventFiltering>
    <ProcessCreate onmatch="include">
      <ParentImage condition="contains">removable</ParentImage>
    </ProcessCreate>
    <FileCreate onmatch="include">
      <TargetFilename condition="begin with">E:\</TargetFilename>
    </FileCreate>
  </EventFiltering>
</Sysmon>
Enter fullscreen mode Exit fullscreen mode

9. Configuration Templates {#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"
    - write_artifact: "/mnt/usb/stage_report.json"
Enter fullscreen mode Exit fullscreen mode

Detection rule template (Sigma-style)

title: Blackglass USB Local Exec Simulation Detection
id: bg-usb-001
status: experimental
description: Detects executable creation on removable volumes with uncommon parent process
logsource:
  product: windows
  service: sysmon
detection:
  selection:
    EventID: 1
    Image|contains: '\removable\'
    ParentImage|not: ['*\explorer.exe', '*\trusted.exe']
  condition: selection
fields: [Image, ParentImage, CommandLine]
falsepositives: [Legitimate USB updates, authorized maintenance tools]
level: medium
tags: [attack.t1091, blackglass_simulation]
Enter fullscreen mode Exit fullscreen mode

10. Running the Tool - CLI Examples {#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

# Export artifacts
./bgctl export --run ./runs/run1.json --format json --dest ./reports/run1_report.json
Enter fullscreen mode Exit fullscreen mode

Restore snapshot

./bgctl snapshot-restore --vm target-vm --snapshot pretest-snapshot
Enter fullscreen mode Exit fullscreen mode

11. MITRE ATT&CK Coverage {#mitre-attack-coverage}

T1091
Replication Through Removable Media 		T1005
Data from Local System
T1068
Exploitation for Privilege Escalation 		T1021.002
Remote Services: SMB
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. Reporting & Remediation Checklist

Checklist

  • [ ] Snapshot restored
  • [ ] Telemetry ingested
  • [ ] Detection rule fired
  • [ ] False positives reviewed
  • [ ] Incident response runbook exercised
  • [ ] MITRE ATT&CK coverage updated

13. Troubleshooting {#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

14. Contributing & Repo Hygiene

Contributions are welcome! Please follow these guidelines:

  • All contributions must maintain the safety-first approach
  • No weaponized code or actual exploits
  • Document all modules with MITRE ATT&CK mappings
  • Include test coverage for new modules
  • Follow the code style in .editorconfig

See CONTRIBUTING.md in the repository for detailed guidelines.

15. Appendix: Sample Configs

Sample Lab Configuration 

lab:
  name: "offline-test-lab"
  hypervisor: "libvirt"
  network:
    type: "isolated"
    subnet: "192.168.100.0/24"

  vms:
    - name: "target-win10"
      os: "windows-10"
      memory: "4096"
      vcpus: 2
      disk: "50G"
      telemetry:
        - sysmon
        - event-logs

    - name: "target-ubuntu"
      os: "ubuntu-22.04"
      memory: "2048"
      vcpus: 2
      disk: "30G"
      telemetry:
        - auditd
        - sysmon-linux

    - name: "collector"
      os: "ubuntu-22.04"
      memory: "4096"
      vcpus: 2
      disk: "100G"
      role: "log-collector"
Enter fullscreen mode Exit fullscreen mode

Sample Detection Rule (Elastic) 

{
  "rule": {
    "name": "Blackglass USB Execution Detected",
    "description": "Detects process execution from removable media paths",
    "severity": "medium",
    "risk_score": 47,
    "query": "event.category:process and process.executable:/media/* or process.executable:E\\:\\\\*",
    "filters": [
      {
        "exists": {
          "field": "process.parent.executable"
        }
      }
    ],
    "tags": ["T1091", "blackglass_simulation", "offline_attack"]
  }
}
Enter fullscreen mode Exit fullscreen mode

16. What's Next {#whats-next}

The Blackglass_Suite project is actively evolving. Upcoming features include:

  • Extended MITRE ATT&CK coverage - More offline technique simulations
  • Automated report generation - Comprehensive PDF/HTML reports with telemetry analysis
  • Integration with SIEM platforms - Direct log shipping to Splunk, Elastic, and others
  • Pre-built lab templates - Ready-to-deploy VM configurations for common scenarios
  • Detection rule library - Growing collection of validated detection rules

Final Notes

Remember: Blackglass_Suite is designed for defensive security research only. Always:

  • Obtain proper authorization
  • Work in isolated environments
  • Document your testing procedures
  • Share findings responsibly
  • Respect ethical boundaries

The goal is to make defenders better at detecting offline threats, not to provide attack tools. Use this responsibly to improve security posture and detection capabilities.

Top comments (0)