Metadata-Version: 2.5
Name: carcara-sec
Version: 0.1.0
Summary: iOS AppSec platform — unified CLI for mobile security tooling
License: MIT
License-File: LICENSE
Keywords: appsec,frida,ios,mobile-security,pentest,red-team
Requires-Python: >=3.13
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: rich>=15.0.0
Requires-Dist: typer>=0.27.1
Description-Content-Type: text/markdown

# Carcará

> iOS AppSec platform — unified CLI for mobile security tooling.

Carcará unifies Frida, Objection, SSH, file transfer, and provisioning profile management into a single CLI, purpose-built for iOS application security testing.

[![Quality](https://github.com/ZeckWork/carcara-sec/actions/workflows/quality.yml/badge.svg)](https://github.com/ZeckWork/carcara-sec/actions/workflows/quality.yml)
[![PyPI](https://img.shields.io/pypi/v/carcara-sec)](https://pypi.org/project/carcara-sec)

```bash
pip install carcara-sec
```

## Requirements

- macOS (primary target)
- Python 3.13+
- [uv](https://github.com/astral-sh/uv) (recommended) or pip
- Xcode command line tools
- Node.js (for bagbak and applesign)

## Installation

```bash
pip install carcara-sec
carcara tools install   # installs frida-tools, objection, bagbak, applesign
```

## Quick start

```bash
# Register a device
carcara device add

# Connect
carcara device connect iphone6

# List processes
carcara frida ps

# Bypass SSL pinning
carcara frida codeshare sensepost/objection-ios-ssl-pinning com.target.app
```

## Device lab

Carcará uses device profiles stored in `~/.carcara/devices/`. The active device is set once and used automatically by every command.

```bash
carcara device connect iphone6
carcara frida ps                        # runs on iphone6
carcara ssh run "ls /var/mobile"        # runs on iphone6
```

---

## Command reference

All commands follow the same pattern:

```
carcara <module> <action> [arguments]
```

---

## device

Manage registered devices. Profiles live in `~/.carcara/devices/`.

| Command | Description |
|---|---|
| `carcara device list` | List all registered devices with online/offline status |
| `carcara device connect <name>` | Connect to a device: starts iproxy, SSH tunnel, checks frida-server |
| `carcara device disconnect` | Tear down all tunnels cleanly |
| `carcara device status` | Show the currently active device and tunnel state |
| `carcara device info <name>` | Print full profile details for a device |
| `carcara device add` | Interactive prompt to register a new device |
| `carcara device remove <name>` | Remove a device profile |

**Examples**

```bash
carcara device list
# iphone6   192.168.1.100   iOS 12.5.8   palera1n   ● online
# iphone13  192.168.1.101   iOS 16.5     dopamine   ○ offline

carcara device connect iphone6
# ✓ SSH reachable
# ✓ frida-server running
# ✓ Active device set to: iphone6

carcara device status
# active device   iphone6
# host            192.168.1.100
# status          ● online
```

---

## frida

Interact with the Frida instrumentation toolkit on the active device.

| Command | Description |
|---|---|
| `carcara frida ps` | List all running processes on the device |
| `carcara frida attach <app>` | Attach to a running process by name |
| `carcara frida attach-pid <pid>` | Attach to a running process by PID |
| `carcara frida run <script> <app>` | Attach to a process and inject a script from the local library |
| `carcara frida spawn <script> <app>` | Spawn an app from scratch and inject a script before execution |
| `carcara frida codeshare <path> <app>` | Run a script directly from Frida CodeShare |
| `carcara frida dump <bundle-id>` | Dump and decrypt an IPA from the device |
| `carcara frida trace <app> [args]` | Trace function calls on the active device |
| `carcara frida gadget` | Connect Frida REPL to an active Frida Gadget via USB |

**Examples**

```bash
carcara frida ps

carcara frida attach com.target.app

carcara frida run ssl-pinning/bypass-generic com.target.app

carcara frida spawn ssl-pinning/bypass-generic com.target.app

carcara frida codeshare sensepost/objection-ios-ssl-pinning com.target.app

carcara frida dump com.target.app
# Saves to ~/Downloads/carcara/com.target.app.ipa

carcara frida trace MyApp -m '*[NSString stringWithFormat:]*'

carcara frida gadget
# Connects to Frida Gadget — requires Xcode attach (see provision workflow)
```

---

## objection

Interact with the Objection runtime mobile exploration toolkit.

| Command | Description |
|---|---|
| `carcara objection explore` | Open the interactive Objection REPL on the active device |
| `carcara objection run <cmd>` | Run a single Objection command non-interactively |
| `carcara objection patchipa <path>` | Patch a local IPA to embed FridaGadget for non-jailbroken devices |
| `carcara objection gadget` | Start an Objection session connected to an active Frida Gadget |

**Examples**

```bash
carcara objection explore

carcara objection run "ios sslpinning disable"

carcara objection patchipa ./MyApp.ipa
# Uses the active provisioning profile — set with carcara provision use <uuid>
```

**Common Objection commands**

```
ios sslpinning disable
ios jailbreak disable
ios keychain dump
ios nsuserdefaults get
ios cookies get
memory list exports <lib>
```

---

## provision

Manage Apple provisioning profiles for IPA patching and re-signing.
Profiles are stored in `~/.carcara/profiles/` — never in `~/Library/MobileDevice/` where Xcode may delete them.

| Command | Description |
|---|---|
| `carcara provision add <path>` | Add a `.mobileprovision` file and optionally set as active |
| `carcara provision list` | List all installed profiles with status |
| `carcara provision use <uuid>` | Set a profile as active by UUID |
| `carcara provision show` | Show details for the active profile, including resolved codesign identity |
| `carcara provision check` | Check if the active profile is valid and not near expiry |
| `carcara provision entitlements` | Export entitlements from the active profile to `entitlements.plist` |
| `carcara provision resign <path>` | Re-sign an IPA with the active profile (no Frida injection) |

**Examples**

```bash
carcara provision add ~/Downloads/work.zeck.app-sec.mobileprovision
# Imports profile, optionally imports existing system profiles
# Prompts to set as active

carcara provision list
# UUID           Name              Bundle ID          Expiry       Status
# TEST-UUID-0001 Carcará Dev       work.zeck.app-sec  2026-01-01   ✓ valid

carcara provision use TEST-UUID-0001

carcara provision show
# name        Carcará Dev
# bundle id   work.zeck.app-sec
# team id     TEAMID1234
# identity    iPhone Developer: ...
# expiry      2026-01-01

carcara provision entitlements -o /tmp
# → /tmp/entitlements.plist

carcara provision resign ./MyApp.ipa
# → MyApp-resigned.ipa
```

---

## transfer

Transfer files and directories between your machine and the device over SCP.

| Command | Description |
|---|---|
| `carcara transfer pull <remote>` | Pull a file from device to local (defaults to `~/Downloads/carcara/`) |
| `carcara transfer push <local> <remote>` | Push a local file to the device |
| `carcara transfer pull-dir <remote>` | Pull a directory recursively from device |
| `carcara transfer push-dir <local> <remote>` | Push a directory recursively to device |

**Examples**

```bash
carcara transfer pull /var/mobile/Documents/secrets.db

carcara transfer push ./patch.dylib /tmp/patch.dylib

carcara transfer pull-dir /var/mobile/Containers/Data/Application/UUID/Documents
```

---

## ssh

Manage SSH connectivity and run remote commands on the device.

| Command | Description |
|---|---|
| `carcara ssh shell` | Open an interactive SSH shell on the active device |
| `carcara ssh run <cmd>` | Run a single command on the device and return output |
| `carcara ssh tunnel <local> <remote>` | Start iproxy USB tunnel manually |
| `carcara ssh copy-id` | Install your local SSH public key on the device |

**Examples**

```bash
carcara ssh shell

carcara ssh run "ls /var/mobile/Documents"

carcara ssh run "ps aux | grep SpringBoard"

carcara ssh copy-id
# Installs ~/.ssh/id_ed25519.pub — no more password prompts
```

---

## tools

Manage the external tools that Carcará depends on.

| Command | Description |
|---|---|
| `carcara tools list` | Show all required tools with installed and required versions |
| `carcara tools check` | Validate installed versions against the manifest |
| `carcara tools install` | Install or upgrade all tools |

**Examples**

```bash
carcara tools list
carcara tools check
carcara tools install
```

---

## Quick reference

```
carcara device    list | connect | disconnect | status | info | add | remove
carcara frida     ps | attach | attach-pid | run | spawn | codeshare | dump | trace | gadget
carcara objection explore | run | patchipa | gadget
carcara provision add | list | use | show | check | entitlements | resign
carcara transfer  pull | push | pull-dir | push-dir
carcara ssh       shell | run | tunnel | copy-id
carcara tools     list | check | install
```

---

## License

MIT
