Skip to content

About

Simple GPO Explorer for CTF challenges. You can drop a zip containing GPOs and analyze them fast. Assisted-by: Claude Sonnet

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

20 Commits

Folders and files

Repository files navigation

Simple GPO Explorer

A web-based analyzer for Group Policy Object (GPO) backup archives. Upload a SYSVOL-style .zip export ({GUID} directories containing GPT.INI), then browse, search and inspect every GPO it contains — security templates, registry policy, client-side extensions, and any recoverable Group Policy Preferences credentials — all in a local dark-mode interface backed by SQLite.


Features

  • Upload & parse GPO backup .zip archives (drag-and-drop or file picker) — a SYSVOL-style layout of {GUID} directories is expected, each containing GPT.INI; directories are discovered recursively, so a zip of an entire Policies folder works as-is
  • Deep artifact parsing for every GPO found in the archive:
    • GPT.INI — GPO version (split into machine/user version numbers)
    • Group Policy\GPE.INI — configured client-side extensions, resolved against a curated list of well-known extension GUIDs (Registry, Security, Folder Redirection, Local Users and Groups, …)
    • SecEdit\GptTmpl.inf (Machine and User) — the UTF-16LE security template, parsed into ordered sections/keys
    • Registry.pol (Machine and User) — the binary registry policy format, fully decoded (REG_SZ, REG_EXPAND_SZ, REG_DWORD, REG_QWORD, REG_MULTI_SZ, REG_BINARY)
    • Group Policy Preferences credential recovery — every Preferences\*.xml file (Groups.xml, Drives.xml, ScheduledTasks.xml, Services.xml, …) is scanned for cpassword attributes, which are decrypted using Microsoft's published AES key (MS14-025 / KB2962486)
    • Parsing failures on any single artifact are recorded as per-GPO warnings rather than aborting the whole upload
  • Archive sets — each upload is stored as its own archive set in SQLite; switch between previously uploaded archives from the dropdown, or delete one entirely
  • GPO table with a live stats bar (GPOs shown, GPOs with credential findings, total decrypted credentials) and columns for name, GPT version, extension count, machine/user policy presence, credential findings and comment
  • Search bar with free text plus key:value operators (see Search operators); multiple tokens combine with AND, any operator can be negated with -
  • GPO detail view for every parsed artifact:
    • GPT.INI summary, extension list, SecEdit sections, decoded Registry.pol entries
    • Credential findings section highlighting any decrypted cpassword values, with the source file and account name
    • File browser — every file inside the GPO is listed and viewable: text and XML are rendered inline (XML pretty-printed, large files truncated), binary files are identified by extension/content sniffing and never have their raw bytes dumped
    • Any parsing errors for that GPO, surfaced individually
  • Display name mapping — upload a markdown file with a table containing {GUID} cells and a display-name column (e.g. exported from GPMC/RSOP) to label otherwise-anonymous GPOs; column order and headers don't matter, only that one cell per row is GUID-shaped
  • Comments — a free-text notes field per GPO, persisted in the database
  • Tags — arbitrary labels per GPO, persisted and searchable with the tag: operator
  • Dark mode UI, no external CDN dependencies — everything (styling, scripting) ships locally

Requirements

  • Python 3.11 or later
  • Pip / venv

Installation

# 1. Clone the repository
git clone https://github.com/BearlyStable/Simple-GPO-Explorer.git
cd Simple-GPO-Explorer

# 2. Create and activate a virtual environment
python -m venv .venv

# Windows
.venv\Scripts\activate

# macOS / Linux
source .venv/bin/activate

# 3. Install dependencies
pip install -r src/requirements.txt

On macOS/Linux you can use the bundled Makefile instead of the steps above:

make setup   # creates src/.venv and installs dependencies
make run     # runs the app (implies setup)

Running the application

cd src
python app.py

The server starts on http://localhost:4000 in debug mode.

For a production deployment (matches what the Docker image runs):

pip install gunicorn
cd src
gunicorn --bind 0.0.0.0:5000 --workers 1 --threads 4 --timeout 120 app:app

Note: The application is intended for local/internal use only. Do not expose it to an untrusted network — uploaded GPO archives can contain decrypted credentials and other sensitive AD configuration.

Useful environment variables:

Variable Default Purpose
SIMPLE_GPO_EXPLORER_SECRET_KEY dev-secret-key-change-me Flask session/flash signing key
SIMPLE_GPO_EXPLORER_DB <instance>/simple_gpo_explorer.sqlite3 SQLite database path
SIMPLE_GPO_EXPLORER_UPLOAD_DIR <instance>/uploads Directory where uploaded archives are stored

Docker

Pull the published image

A GitHub Actions workflow (.github/workflows/docker-publish.yml) builds and publishes the image to the GitHub Container Registry:

  • Every push to main publishes ghcr.io/bearlystable/simple-gpo-explorer:latest
  • Every published GitHub Release publishes a version-tagged image, e.g. ghcr.io/bearlystable/simple-gpo-explorer:1.0.0 (and 1.0)
docker pull ghcr.io/bearlystable/simple-gpo-explorer:latest

The ghcr.io/bearlystable/simple-gpo-explorer package must be set to public visibility in its GitHub package settings the first time it's published, otherwise docker pull requires authentication.

Build and run locally

cd docker
docker compose up -d --build

The app is then reachable at http://localhost:5000.

Configuration

Copy docker/.env.example to docker/.env to override defaults (docker compose loads it automatically):

cp docker/.env.example docker/.env
Variable Default Purpose
SIMPLE_GPO_EXPLORER_SECRET_KEY dev-secret-key-change-me Flask session/flash signing key
SIMPLE_GPO_EXPLORER_PORT 5000 Host port the web UI is published on

Persistent data

The SQLite database and every uploaded .zip archive live under /app/instance inside the container, backed by the named volume simple_gpo_explorer_data. Stopping, removing or rebuilding the container does not touch this volume:

docker compose down      # data preserved
docker compose down -v   # -v also deletes simple_gpo_explorer_data — be sure first

Moving the image to an offline machine

make release   # builds the image and exports it to dist/simple-gpo-explorer-<timestamp>.tar.gz

The target machine only needs the tarball plus the docker/ directory (no source tree, no registry or internet access required):

docker load -i simple-gpo-explorer-<timestamp>.tar.gz
docker compose -f docker/docker-compose.yml up -d

Backup and restore

Back up the named volume to a tarball:

docker run --rm -v simple_gpo_explorer_data:/data -v "$PWD":/backup alpine \
  tar czf /backup/simple-gpo-explorer-backup.tar.gz -C /data .

Restore it by extracting the tarball back into the volume, then docker compose up -d.

See docker/README.md for the full walkthrough.


Usage

  1. Open http://localhost:4000 (or :5000 under Docker) in your browser.
  2. Click Upload GPO Archive in the top-right corner.
  3. Drag and drop (or browse to) a .zip export — a SYSVOL-style layout of {GUID} directories, each containing GPT.INI (e.g. a zip of a domain controller's SYSVOL\<domain>\Policies folder).
  4. Every GPO in the archive is parsed and stored as a new archive set; switch between archive sets with the dropdown in the top bar.
  5. Use the search bar to filter by name, GUID, version, policy scope, credential findings, notes or tags.
  6. Click any row to open the GPO detail view with every parsed artifact, the file browser, comments and tags.
  7. Optionally click Display Names to upload a markdown GUID → name mapping and label the archive set's GPOs.

Example archive layout

{31B2F340-016D-11D2-945F-00C04FB984F9}/
├── GPT.INI
├── Group Policy/
│   └── GPE.INI
├── MACHINE/
│   ├── Microsoft/Windows NT/SecEdit/GptTmpl.inf
│   ├── Registry.pol
│   └── Preferences/Groups/Groups.xml
└── USER/
    ├── Registry.pol
    └── Preferences/Drives/Drives.xml

Multiple {GUID} directories in the same zip are all discovered and parsed as part of one archive set.


Project structure

Simple-GPO-Explorer/
├── LICENSE
├── Makefile             # setup / run / docker-* / release targets
├── .dockerignore         # Applies to the docker build context (repo root)
├── src/
│   ├── app.py            # Flask application — routes, upload handling, REST API
│   ├── requirements.txt  # Python dependencies
│   ├── gpo_analyzer/     # Parsing engine (no Flask dependency)
│   │   ├── analyzer.py         # Orchestrates parsing of a single GPO directory
│   │   ├── extractor.py        # Zip upload/extraction, zip-slip protection, GPO discovery
│   │   ├── gpt_ini.py          # GPT.INI parser
│   │   ├── gpe_ini.py          # GPE.INI / client-side extension parser
│   │   ├── secedit.py          # SecEdit\GptTmpl.inf parser
│   │   ├── registry_pol.py     # Binary Registry.pol parser
│   │   ├── preferences.py      # Group Policy Preferences cpassword scanner/decryptor
│   │   ├── file_inspector.py   # Binary/text detection for the in-browser file viewer
│   │   ├── displayname_md.py   # Markdown GUID → display-name table parser
│   │   ├── pathutils.py        # Case-insensitive path resolution
│   │   └── db.py               # SQLite schema, migrations, archive/GPO persistence
│   ├── templates/
│   │   ├── base.html      # Shared layout, upload/display-name modals
│   │   ├── index.html     # Archive set / GPO table page
│   │   └── detail.html    # GPO detail page
│   ├── static/
│   │   ├── style.css      # All custom styles (dark theme, badges, layout)
│   │   └── app.js          # All application logic (API calls, search, rendering)
│   └── instance/          # Created at runtime — SQLite DB and stored upload archives
└── docker/
    ├── Dockerfile          # Production image (gunicorn, python:3.12-slim)
    ├── docker-compose.yml  # Compose file with a named volume for persistence
    ├── .env.example        # Template for docker/.env overrides
    └── README.md           # Extended Docker usage, backup/restore, offline transfer

API endpoints

Method Path Description
GET / Main web UI (archive set / GPO table)
GET /gpo/<archive_set_id>/<guid> GPO detail page
GET /api/archive-sets List all archive sets
POST /api/archive-sets Upload and parse a GPO backup .zip (multipart field: gpo_zip)
GET /api/archive-sets/<id> Get one archive set's metadata
DELETE /api/archive-sets/<id> Delete an archive set, its GPOs and its stored archive file
GET /api/archive-sets/<id>/gpos List summarized GPOs in an archive set
GET /api/archive-sets/<id>/gpos/<guid> Full parsed detail for one GPO
PATCH /api/archive-sets/<id>/gpos/<guid>/comment Set or clear a GPO's notes text
PATCH /api/archive-sets/<id>/gpos/<guid>/tags Replace a GPO's tag list ({"tags": [...]})
GET /api/archive-sets/<id>/gpos/<guid>/files/<relpath> View one file's content from within a GPO (binary-safe; re-reads directly from the stored zip)
POST /api/archive-sets/<id>/display-names Upload a markdown GUID → display-name mapping (multipart field: display_names_md)

Search operators

The search bar accepts plain text (matches display name, GUID, comment and tags) and structured key:value operators. Multiple tokens are combined with AND. Prefix any token with - to negate it. The * character acts as a wildcard.

Operator Description Examples
displayname: Display name displayname:*policy*
guid: GPO GUID guid:31B2F340*
version: Exact GPT.INI version number version:3
machine:yes/no Has machine-side policy machine:yes
user:yes/no Has user-side policy user:no
creds:yes/no Has decrypted GPP credentials creds:yes
notes:yes/no Has a comment -notes:yes
comment: Comment text comment:*legacy*
tag:value GPOs carrying a specific tag tag:reviewed, -tag:stale

Examples:

# GPOs with recoverable credentials
creds:yes

# Named, machine-only policies without a review comment
displayname:*policy* machine:yes user:no -notes:yes

# Everything tagged "legacy"
tag:legacy

License

Simple GPO Explorer is licensed under the GNU GPLv3.

Third-party software

This project is built on top of the following open-source software, installed via pip at setup/build time (none of it is redistributed as source within this repository):

Project License Role
Flask BSD-3-Clause Web framework
Werkzeug BSD-3-Clause WSGI toolkit (Flask dependency)
gunicorn MIT Production WSGI server (Docker image)
PyCryptodome BSD-2-Clause AES decryption of Group Policy Preferences cpassword values

All of the above are permissively licensed, so there is no copyleft-compatibility concern with distributing this project under GPLv3.

About

Simple GPO Explorer for CTF challenges. You can drop a zip containing GPOs and analyze them fast. Assisted-by: Claude Sonnet

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages