# GATEkeeper

<div align="center">

**GATEkeeper by ek0mssavior.dev**

**Advanced Browser Automation for Gatekeeper Testing & Network Recon**

[Features](#features) • [Installation](#installation) • [Usage](#usage) • [Bulk Scanning](#bulk-scanning) • [Options](#options) • [Output](#output) • [Disclaimer](#disclaimer)

</div>

---

## Overview

GATEkeeper is a Playwright-powered reconnaissance tool for authorized web application testing.

It launches a Chromium browser, simulates human-like interaction, captures browser network activity, tracks redirects and URL changes, logs console messages, saves the final rendered page, and optionally dumps response bodies for offline analysis.

GATEkeeper also performs lightweight preflight reconnaissance before browser interaction, including DNS resolution, target IP collection, common web port checks, service hints, TLS certificate metadata, and triage scoring.

It is useful for testing applications where content, redirects, API calls, authentication workflows, or client-side behavior only appear after JavaScript execution, user interaction, authentication, or delayed page activity.

---

## Features

* Interactive prompt mode or command-line mode
* Single-target scanning
* Bulk scanning from a file of domains or URLs
* Headless or visible Chromium browser automation
* Lightweight preflight recon:

  * DNS resolution
  * Target IP collection
  * Canonical name and alias collection
  * Common web port checks
  * Service hints for discovered ports
  * TLS certificate metadata
  * Subject Alternative Name preview
* Simulated human-like interaction:

  * Mouse movement
  * Page clicks
  * Scrolling
  * Keyboard events
  * Viewport resizing
* Captures network requests and responses
* Captures failed requests
* Captures JavaScript console messages
* Tracks URL changes and redirect responses
* Handles binary/compressed POST bodies safely
* Loads cookies for authenticated testing
* Supports custom HTTP headers
* Supports custom User-Agent strings
* Waits for a specific CSS selector before interaction
* Optional response body dumping
* Basic technology fingerprinting
* Basic security header analysis
* Structured `report.json` generation
* Bulk `aggregate_report.json` generation
* Triage scoring to help prioritize interesting targets

---

## Installation

### Requirements

* Python 3.10+
* Playwright

### Clone the Repository

```bash
git clone https://git.churchofmalware.org/ek0mssavi0r/GATEkeeper.git
cd GATEkeeper
```

### Install Playwright

```bash
pip install playwright --break-system-packages
```

### Install Chromium

```bash
python3 -m playwright install chromium
```

If Playwright reports missing browser dependencies, run:

```bash
python3 -m playwright install-deps chromium
python3 -m playwright install chromium
```

---

## Usage

GATEkeeper supports interactive mode, command-line mode, and bulk mode.

### Interactive Mode

```bash
python3 gatekeeper.py
```

You will be prompted for:

* Target URL
* Output directory
* Headless mode
* Interaction duration

---

## Command-Line Mode

### Basic Scan

```bash
python3 gatekeeper.py https://example.com
```

### Headless Scan

```bash
python3 gatekeeper.py https://example.com --headless
```

### Longer Interaction Window

```bash
python3 gatekeeper.py https://example.com --duration 90
```

### Save Response Bodies and Generate Report

```bash
python3 gatekeeper.py https://example.com --headless --duration 60 --save-bodies --report
```

### Authenticated Testing with Cookies

```bash
python3 gatekeeper.py https://example.com/dashboard --cookies cookies.json --report
```

### Add Custom Headers

```bash
python3 gatekeeper.py https://example.com/dashboard \
  --header "Authorization: Bearer TOKEN_HERE" \
  --header "X-Test-Mode: authorized"
```

### Custom User-Agent

```bash
python3 gatekeeper.py https://example.com --user-agent "Mozilla/5.0 CustomTestAgent"
```

### Wait for a DOM Element Before Interacting

```bash
python3 gatekeeper.py https://example.com/dashboard --wait-selector "#dashboard"
```

### Non-Interactive Mode

```bash
python3 gatekeeper.py https://example.com --non-interactive --headless --report
```

---

## Bulk Scanning

GATEkeeper can scan a list of targets from a text file.

Create a file like:

```text
app.example.com
api.example.com
portal.example.com
https://admin.example.com
```

Run:

```bash
python3 gatekeeper.py -i subs.txt --headless --duration 15 --timeout 30000 --report --concurrency 3 --delay 1
```

Bare domains are automatically normalized with `https://` unless another scheme is specified.

Example with a full path:

```bash
python3 gatekeeper.py \
  -i /home/ek0ms/kctcs/subs.txt \
  --headless \
  --duration 10 \
  --timeout 25000 \
  --report \
  --concurrency 3 \
  --delay 1
```

Bulk mode creates one folder per target and writes a ranked aggregate report.

Default bulk output:

```text
gatekeeper_bulk_results/
```

Example:

```text
gatekeeper_bulk_results/
├── aggregate_report.json
├── app.example.com/
│   ├── network_capture.json
│   ├── report.json
│   ├── final_page.html
│   ├── final_screenshot.png
│   └── console_log.txt
└── api.example.com/
    ├── network_capture.json
    ├── report.json
    ├── final_page.html
    ├── final_screenshot.png
    └── console_log.txt
```

For large scopes, start without `--save-bodies` to keep scans fast and output smaller. Use `--save-bodies` later on the most interesting hosts.

---

## Options

| Argument                  | Description                                                                                                   |
| ------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `url`                     | Target URL. Optional if using interactive mode or bulk mode.                                                  |
| `-i`, `--input-file FILE` | File containing targets, one domain or URL per line.                                                          |
| `-o`, `--output DIR`      | Output directory. Defaults to `<domain>_bang/` for single scans or `gatekeeper_bulk_results/` for bulk scans. |
| `--headless`              | Run Chromium without a visible browser window.                                                                |
| `--duration N`            | Interaction duration in seconds. Default: `45`.                                                               |
| `--timeout N`             | Navigation timeout in milliseconds. Default: `60000`.                                                         |
| `--cookies FILE`          | Load cookies from a Playwright-compatible JSON cookie file.                                                   |
| `--header "Name: Value"`  | Add a custom HTTP header. Can be used multiple times.                                                         |
| `--user-agent STRING`     | Override the default User-Agent.                                                                              |
| `--wait-selector CSS`     | Wait for a CSS selector before starting interaction.                                                          |
| `--save-bodies`           | Save response bodies to disk.                                                                                 |
| `--report`                | Generate `report.json`.                                                                                       |
| `--non-interactive`       | Do not prompt for missing values.                                                                             |
| `--concurrency N`         | Number of targets to scan at once in bulk mode. Default: `2`.                                                 |
| `--delay N`               | Delay in seconds after each target finishes. Default: `0`.                                                    |
| `--scheme http/https`     | Default scheme for bare domains in input files. Default: `https`.                                             |

---

## Output

By default, single-target results are saved in a directory named after the target domain.

Example:

```text
example.com_bang/
```

Generated files:

| File / Directory        | Description                                                                              |
| ----------------------- | ---------------------------------------------------------------------------------------- |
| `network_capture.json`  | Full request, response, failure, URL change, console log, recon, and saved body metadata |
| `final_page.html`       | Final rendered DOM after interaction                                                     |
| `final_screenshot.png`  | Full-page screenshot                                                                     |
| `console_log.txt`       | JavaScript console messages                                                              |
| `report.json`           | Structured report generated with `--report`                                              |
| `response_bodies/`      | Saved response bodies generated with `--save-bodies`                                     |
| `aggregate_report.json` | Bulk scan summary generated in bulk mode                                                 |

---

## Terminal Summary

Each target prints a summary like:

```text
============================================================
GATEKEEPER SUMMARY
============================================================
Initial URL: https://example.com
Final URL:   https://example.com/
Title:       Example Domain
Requests:    12
Responses:   12
Failures:    0
Console:     1
URL changes: 0
Bodies saved:0

------------------------------------------------------------
LIGHTWEIGHT RECON
------------------------------------------------------------
Host:        example.com
IPs:         ['93.184.216.34']
Canonical:   example.com
Aliases:     []
Open ports:  [80, 443]

[+] Service hints:
  - 80: http
  - 443: https

[+] TLS info:
  Not before: May 28 15:39:24 2026 GMT
  Not after:  Dec 12 15:39:24 2026 GMT
  SAN count:  3
    - example.com
    - www.example.com

[+] No HTTP redirect responses captured.

[-] No configured interesting endpoint terms captured.

[+] Detected technologies:
  - Nginx

[!] Missing common security headers:
  - content-security-policy
  - permissions-policy

[+] Final HTML captured and does not obviously look stuck on a spinner.

[+] Triage score: 12
```

---

## Report Contents

When `--report` is used, GATEkeeper generates `report.json` with:

* Target URL
* Final URL
* Final page title
* Triage score
* DNS and IP information
* Canonical name and aliases
* Open common web ports
* Service hints
* TLS certificate metadata
* Total requests
* Total responses
* Failed request count
* Console message count
* URL changes
* Redirects
* Status code summary
* Resource type summary
* Interesting endpoint matches
* Basic detected technologies
* Common security header analysis
* Saved response body metadata

Example:

```json
{
  "target": "https://example.com",
  "final_url": "https://example.com/dashboard",
  "final_title": "Dashboard",
  "triage_score": 18,
  "recon": {
    "host": "example.com",
    "dns": {
      "canonical_name": "example.com",
      "aliases": [],
      "ips": ["93.184.216.34"]
    },
    "open_ports": [80, 443],
    "services": [
      {"port": 80, "hint": "http"},
      {"port": 443, "hint": "https"}
    ],
    "tls": {
      "not_before": "May 28 15:39:24 2026 GMT",
      "not_after": "Dec 12 15:39:24 2026 GMT",
      "san": ["example.com", "www.example.com"]
    }
  },
  "summary": {
    "total_requests": 134,
    "total_responses": 129,
    "failed_requests": 5,
    "redirects_detected": 2,
    "response_bodies_saved": 48
  },
  "technologies": [
    "Cloudflare",
    "React",
    "Google Analytics"
  ],
  "security_headers": {
    "strict-transport-security": {
      "present": true,
      "value": "max-age=31536000"
    },
    "content-security-policy": {
      "present": false,
      "value": null
    }
  }
}
```

---

## Aggregate Report

Bulk mode writes:

```text
aggregate_report.json
```

The aggregate report includes:

* Total targets
* Completed scans
* Errors
* Results ranked by triage score
* Final URL
* Final title
* IPs
* Canonical name
* Aliases
* Open ports
* Service hints
* TLS expiration
* Request/response/failure counts
* URL change count
* Detected technologies
* Interesting endpoint count

This makes it easier to triage large target lists without opening every folder manually.

---

## Triage Score

GATEkeeper assigns a lightweight triage score to help prioritize results.

The score increases for signals such as:

* Non-standard web ports
* URL changes
* Interesting endpoint terms
* Missing common security headers
* Final URL differing from the initial target
* Certain detected technologies

The score is not a vulnerability rating. It is a sorting helper for recon workflows.

---

## Cookie File Format

The cookie file must be a JSON array of cookie objects accepted by Playwright.

Example:

```json
[
  {
    "name": "sessionid",
    "value": "abc123",
    "domain": "example.com",
    "path": "/",
    "httpOnly": true,
    "secure": true,
    "sameSite": "Lax"
  }
]
```

---

## How It Works

1. Normalizes the target URL.
2. Runs lightweight preflight recon:

   * Resolves DNS
   * Collects target IPs
   * Checks common web ports
   * Adds service hints
   * Pulls TLS certificate metadata when HTTPS is open
3. Launches a Chromium browser with a realistic viewport and User-Agent.
4. Optionally loads cookies and custom headers.
5. Navigates to the target URL.
6. Optionally waits for a CSS selector.
7. Simulates browser interaction:

   * Mouse movement
   * Clicks
   * Scrolling
   * Keyboard input
   * Viewport resizing
8. Captures requests, responses, failed requests, redirects, URL changes, and console logs.
9. Saves final HTML and screenshot.
10. Optionally saves response bodies.
11. Optionally generates a structured report.
12. In bulk mode, writes an aggregate report ranked by triage score.

---

## Disclaimer

This tool is intended for authorized security testing, research, educational assessments only.



---

<div align="center">

**Happy Hacking — Authorized Testing Only**

</div>