Metadata-Version: 2.4
Name: screentime-brute
Version: 0.2.1
Summary: Brute-force and analysis tools for macOS Screen Time passcodes
Author: Kieran Klukas
License-Expression: MIT
License-File: LICENSE.md
Requires-Python: >=3.10
Requires-Dist: rich
Description-Content-Type: text/markdown

# screentime-brute

brute-force and analysis tools for macOS Screen Time passcodes. uses UI automation + clock manipulation to bypass lockout timers and try all 10,000 PINs in frequency order.

## Structure

```
bruteforce/
  bruteforce.py           # core logic (PIN entry, lockout bypass, state management)
  bruteforce_tui.py       # rich TUI visualization wrapper
  bruteforce_ui.sh        # shell-based UI automation approach
  pin_frequency.csv       # PINs ordered by frequency (most common first)
tools/
  inspect_passcode.swift  # inspect Screen Time passcode storage
  decode_passcode.swift   # decode stored passcode data
  bruteforce_poc.swift    # swift proof-of-concept brute-force
docs/
  screentime-passcode-internals.md  # deep dive on Screen Time internals
```

## Usage

Switch to root first — the brute-force needs clock manipulation privileges:

```bash
sudo su
uvx screentime-brute
```

**Flags:**

| Flag      | Description                          |
| --------- | ------------------------------------ |
| `--demo`  | Demo mode (no system changes)        |
| `--reset` | Clear state and start fresh          |

Or run from source:

```bash
sudo su
pip install .
screentime-brute
```

## Requirements

- macOS with Screen Time enabled
- Accessibility permissions for Terminal
- Python 3.10+
- Root access (for clock manipulation)

## How It Works

1. Opens the Screen Time passcode dialog via AppleScript
2. Enters PINs from a frequency-sorted list (most common first)
3. When locked out, advances the system clock to skip the timer
4. Resets the clock via NTP after bypass
5. Tracks state in `.bruteforce_state.json` for resumable attacks

## Swift Tools

```bash
# Decode stored passcode data
swiftc tools/decode_passcode.swift -o decode_passcode && ./decode_passcode

# Inspect passcode storage at runtime
swiftc tools/inspect_passcode.swift -o inspect_passcode && ./inspect_passcode

# XPC-based brute-force proof of concept
swiftc tools/bruteforce_poc.swift -o bruteforce_poc && ./bruteforce_poc
```

<p align="center">
    <img src="https://raw.githubusercontent.com/taciturnaxolotl/carriage/main/.github/images/line-break.svg" />
</p>

<p align="center">
    <i><code>&copy; 2026-present <a href="https://dunkirk.sh">Kieran Klukas</a></code></i>
</p>

<p align="center">
    <a href="https://github.com/taciturnaxolotl/screentime/blob/main/LICENSE.md"><img src="https://img.shields.io/static/v1.svg?style=for-the-badge&label=License&message=MIT&logoColor=d9e0ee&colorA=363a4f&colorB=b7bdf8"/></a>
</p>
