frooky 0.1.3__tar.gz → 0.2.1__tar.gz

frooky-0.2.1/.github/copilot-instructions.md

@@ -0,0 +1,260 @@
+# Copilot Instructions for Frooky
+
+## Project Overview
+
+**Frooky** is a Frida-powered dynamic instrumentation tool for mobile app security testing on Android and iOS. It allows security testers to hook Java/Kotlin methods and native C/C++ functions using simple JSON configuration files.
+
+### Key Technologies
+
+- **Languages**: Python (CLI; see `requires-python` in [`pyproject.toml`](../pyproject.toml)), TypeScript/JavaScript (Frida agent)
+- **Frameworks**: Frida (dynamic instrumentation), setuptools (Python packaging)
+- **Build Tools**: npm/Node.js (for agent compilation), Python build module
+- **Package Management**: pip (Python), npm (Node.js)
+
+## Project Structure
+
+```bash
+frooky/
+├── frooky/                          # Main Python package
+│   ├── __init__.py                 # Package initialization
+│   ├── cli.py                      # Command-line interface entry point
+│   ├── frida_runner.py             # Core Frida execution logic
+│   └── agent/                      # Frida agent (TypeScript/JavaScript)
+│       ├── package.json            # Node.js dependencies
+│       ├── tsconfig.json           # TypeScript configuration
+│       ├── build.js                # Custom build script
+│       ├── android/                # Android-specific agent code
+│       ├── ios/                    # iOS-specific agent code
+│       └── dist/                   # Compiled agent artifacts (git-ignored)
+│           ├── agent-android.js    # Built Android agent
+│           ├── agent-ios.js        # Built iOS agent
+│           └── version.json        # Version metadata
+├── docs/                            # Documentation
+│   ├── develop.md                  # Development setup guide
+│   ├── usage.md                    # Usage documentation
+│   └── examples/                   # Example hook configurations
+├── .github/
+│   └── workflows/                  # CI/CD pipelines
+│       ├── build.yml               # Package build workflow (reusable)
+│       ├── test-build.yml          # PR/push verification
+│       ├── publish.yml             # PyPI publishing
+│       └── sync-labels.yml         # Label management
+├── pyproject.toml                  # Python project configuration
+├── compileAgent.sh                 # Agent build helper script
+└── README.md                       # Main project documentation
+```
+
+## Build System & Workflow
+
+### Two-Stage Build Process
+
+Frooky uses a **two-stage build** that must be executed in order:
+
+1. **Agent Compilation** (TypeScript → JavaScript):
+
+   ```bash
+   ./compileAgent.sh --prod    # Production build (minified)
+   ./compileAgent.sh --dev     # Development build (unminified)
+   ```
+    - Runs inside [`frooky/agent/`](../frooky/agent/) directory
+    - Executes `npm ci` to install dependencies
+    - Compiles TypeScript sources from [`frooky/agent/android/`](../frooky/agent/android/) and [`frooky/agent/ios/`](../frooky/agent/ios/) subdirectories
+    - Outputs to [`frooky/agent/dist/`](../frooky/agent/dist/) as `agent-{android,ios}.js`
+    - **CRITICAL**: Agent artifacts MUST exist before Python package build
+
+2. **Python Package Build**:
+
+   ```bash
+   python -m build
+   ```
+    - Packages the Python CLI and includes pre-built agent artifacts
+    - Uses `setuptools-scm` for versioning from git tags
+    - Outputs wheel (`.whl`) and source tarball (`.tar.gz`) to `dist/`.
+
+### Development Setup
+
+To set up a local development environment:
+
+```bash
+# 1. Create and activate Python virtual environment
+python3 -m venv venv
+source venv/bin/activate
+
+# 2. Compile Frida agents
+./compileAgent.sh --dev
+
+# 3. Install CLI in editable mode
+pip install -e .
+
+# 4. Verify installation
+which frooky  # Should point to venv/bin/frooky
+frooky --help
+```
+
+### Watch Mode for Active Development
+
+For iterative agent development, use watch mode:
+
+```bash
+cd frooky/agent
+npm run watch-android   # Auto-recompile on Android agent changes
+npm run watch-ios       # Auto-recompile on iOS agent changes
+```
+
+Note: Use `watch-android` and/or `watch-ios` depending on which platform you're working on.
+
+## Testing & CI/CD
+
+### Test Infrastructure
+
+- **No unit tests currently exist** - the project only does CI verification at the moment, but testing of the codebase is in planning
+- **CI Verification** ([`.github/workflows/test-build.yml`](workflows/test-build.yml)):
+    - Builds the package (agent + Python wheel)
+    - Verifies wheel can be installed
+    - Checks that `frooky --help` runs successfully
+    - Validates agent artifacts are included in wheel: `frooky/agent/dist/agent-android.js` and `frooky/agent/dist/agent-ios.js`
+
+### Running CI Checks Locally
+
+```bash
+# Full build verification (mimics CI)
+./compileAgent.sh --prod
+python -m build
+python -m pip install dist/*.whl
+frooky --help
+
+# Verify agent artifacts in wheel
+unzip -l dist/*.whl | grep "frooky/agent/dist/agent-android.js"
+unzip -l dist/*.whl | grep "frooky/agent/dist/agent-ios.js"
+```
+
+## Important Gotchas & Considerations
+
+### 1. **Agent Artifacts Must Be Built First**
+
+- **ALWAYS** run `./compileAgent.sh` before `python -m build`
+- Python packaging will fail or produce incomplete artifacts if agents are missing
+- The [`compileAgent.sh`](../compileAgent.sh) script must be executable (`chmod +x compileAgent.sh`)
+
+### 2. **Version Management**
+
+- Version is determined by `setuptools-scm` from git tags and commits
+- Requires full git history: `git clone` without depth restrictions or fetch with `fetch-depth: 0` in CI
+- Generated version file: `frooky/_version.py` (git-ignored, auto-created during build)
+- **Do not manually edit version numbers**
+
+### 3. **Node.js Environment**
+
+- Node.js version is pinned in CI (see `actions/setup-node` in [`.github/workflows/build.yml`](workflows/build.yml))
+- Use `npm ci` (not `npm install`) for consistent dependency installation
+- Package lock file is at [`frooky/agent/package-lock.json`](../frooky/agent/package-lock.json)
+
+### 4. **Python Version Compatibility**
+
+- Minimum supported Python is defined by `requires-python` in [`pyproject.toml`](../pyproject.toml)
+- The set of versions exercised in CI is defined in [`.github/workflows/`](workflows/) (see `actions/setup-python` steps)
+- Uses modern Python features (e.g., `from __future__ import annotations`)
+
+### 5. **Frida Dependencies**
+
+- Frida dependency constraints are defined in [`pyproject.toml`](../pyproject.toml) under `project.dependencies`
+- These are system-dependent native packages that may take time to install
+
+### 6. **Output Files**
+
+- Default output: `output.json` (git-ignored)
+- Output format: JSON Lines (NDJSON) - one JSON object per line
+- Use `jq . output.json` to pretty-print
+
+### 7. **Git Pager Issues**
+
+- **ALWAYS** use `git --no-pager` when running git commands programmatically
+- Example: `git --no-pager status`, `git --no-pager diff`
+
+## Common Tasks
+
+### Modifying the frooky 
+
+1. Edit TypeScript files in [`frooky/agent/android/`](../frooky/agent/android/) or [`frooky/agent/ios/`](../frooky/agent/ios/)
+2. Recompile: `cd frooky/agent && npm run dev-{android|ios}`
+3. Test locally with `pip install -e .` and run `frooky` commands
+4. Run `frooky --help` to make sure the agent scripts are properly compiled
+
+### Modifying Python CLI
+
+1. Edit [`frooky/cli.py`](../frooky/cli.py) or [`frooky/frida_runner.py`](../frooky/frida_runner.py)
+2. Changes are immediately available with `pip install -e .`
+3. Test with `frooky --help` or relevant commands
+
+### Adding Dependencies
+
+- **Python**: Add to `dependencies` array in [`pyproject.toml`](../pyproject.toml)
+- **Node.js**: Run `cd frooky/agent && npm install --save-dev <package>`
+
+### Documentation Updates
+
+- Main docs are in [`docs/`](../docs/) directory
+- README.md provides quick start and examples
+- Usage guide: [`docs/usage.md`](../docs/usage.md)
+- Development guide: [`docs/develop.md`](../docs/develop.md)
+
+### Adding Examples
+
+- Main examples are in [`docs/examples`](../docs/examples/) directory
+- Add new examples to demonstrate a new feature
+
+### Modifying Examples
+
+- Main examples are in [`docs/examples`](../docs/examples/) directory
+- Modify existing examples if a feature or the public API changes
+
+## Key Files to Understand
+
+### Python Side
+
+- **[`frooky/cli.py`](../frooky/cli.py)**: Argument parsing, CLI entry point
+- **[`frooky/frida_runner.py`](../frooky/frida_runner.py)**: Core logic for loading hooks, attaching to processes, injecting agents
+- **[`pyproject.toml`](../pyproject.toml)**: Project metadata, dependencies, build configuration
+
+### Agent Side
+
+- **[`frooky/agent/build.js`](../frooky/agent/build.js)**: Custom build orchestrator (handles TypeScript compilation, file watching)
+- **[`frooky/agent/android/`](../frooky/agent/android/)**: Android-specific hook implementations
+- **[`frooky/agent/ios/`](../frooky/agent/ios/)**: iOS-specific hook implementations
+- **[`frooky/agent/package.json`](../frooky/agent/package.json)**: Frida bridge dependencies, build scripts
+
+## Workflow for Code Changes
+
+1. **Identify scope**: Python CLI, Android agent, iOS agent, docs or examples?
+2. **Set up dev environment**: Virtual env + compile agents
+3. **Make changes**: Edit relevant files
+4. **Rebuild as needed**:
+    - Android agent changes: `cd frooky/agent && npm run dev-android`
+    - iOS agent changes: `cd frooky/agent && npm run dev-ios`
+    - Python changes: No rebuild needed with `pip install -e .`
+5. **Test manually**: Run `frooky` commands against test apps/hooks
+6. **Verify CI would pass**: Run full build + install verification locally
+7. **Update docs** if user-facing behavior changes
+8. **Update examples** if an example exists or it makes sense to make one for a new feature
+9. **Update Copilot instructions** in [`.github/copilot-instructions.md`](copilot-instructions.md) if needed
+
+## Platform-Specific Notes
+
+### Android
+
+- Hooks Java/Kotlin methods using Frida's Java bridge (`frida-java-bride`)
+- Class names use Java notation: `android.security.keystore.KeyGenParameterSpec$Builder`
+- Can hook constructors with `$init` method name
+
+### iOS
+
+- Hooks Objective-C and Swift methods
+- Uses Frida's ObjC and Swift bridges (`frida-objc-bridge` and `frida-swift-bridge`)
+- Method syntax differs from Android (see [`docs/usage.md`](../docs/usage.md))
+
+## Debugging Tips
+
+- **Agent not loading**: Check that `frooky/agent/dist/` contains `agent-{platform}.js` and is recent
+- **Import errors**: Ensure you're using the venv Python (`which python`)
+- **Frida connection issues**: Verify target device has `frida-server` running
+- **Build failures**: Check Node.js version (needs 24+), ensure [`compileAgent.sh`](../compileAgent.sh) is executable

frooky-0.2.1/.github/scripts/android/install-frida-server.sh

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Download and setup frida-server
+FRIDA_VERSION=$(frida --version) && echo "Frida version: $FRIDA_VERSION" && wget "https://github.com/frida/frida/releases/download/${FRIDA_VERSION}/frida-server-${FRIDA_VERSION}-android-x86_64.xz" && unxz "frida-server-${FRIDA_VERSION}-android-x86_64.xz" && adb push "frida-server-${FRIDA_VERSION}-android-x86_64" /data/local/tmp/frida-server
+adb shell "chmod 755 /data/local/tmp/frida-server"
+
+# Start frida-server in background
+adb shell "nohup /data/local/tmp/frida-server >/data/local/tmp/frida.log 2>&1 </dev/null &"
+
+sleep 2
+adb shell "ps | grep frida-server"

frooky-0.2.1/.github/scripts/android/prep-device.sh

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if adb root >/dev/null 2>&1; then
+  adb wait-for-device
+  adb shell setenforce 0 >/dev/null 2>&1 || true
+fi

frooky-0.2.1/.github/scripts/create-job-summary.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Usage: create-job-summary.sh <platform>
+# Example: create-job-summary.sh android
+
+PLATFORM="${1:-}"
+
+if [ -z "$PLATFORM" ]; then
+  echo "Error: Platform argument required (android or ios)"
+  exit 1
+fi
+
+RESULTS_DIR="${PLATFORM}-test-results"
+PLATFORM_TITLE="$(echo "$PLATFORM" | awk '{print toupper(substr($0,1,1)) tolower(substr($0,2))}')"
+
+# Add evaluation results at the top
+if [ -f evaluation.txt ]; then
+  cat evaluation.txt
+  echo ""
+  echo "---"
+  echo ""
+fi
+
+echo "# $PLATFORM_TITLE Test Results"
+echo ""
+
+echo "## frooky"
+echo ""
+echo '```sh'
+cat "$RESULTS_DIR/frooky.log" 2>/dev/null || echo "No frooky.log found"
+echo ""
+echo '```'
+echo ""
+
+echo "## maestro"
+echo ""
+echo '```sh'
+cat "$RESULTS_DIR/auto.log" 2>/dev/null || echo "No auto.log found"
+echo '```'
+echo ""
+echo ""
+
+echo "Job summary created for $PLATFORM_TITLE tests" >&2

frooky-0.2.1/.github/scripts/evaluate-results.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Usage: evaluate-results.sh <platform>
+# Example: evaluate-results.sh android
+
+PLATFORM="${1:-}"
+
+if [ -z "$PLATFORM" ]; then
+  echo "Error: Platform argument required (android or ios)"
+  exit 1
+fi
+
+EXAMPLE_DIR="docs/examples/${PLATFORM}-app"
+
+cd "$EXAMPLE_DIR"
+chmod +x ../evaluate.sh
+../evaluate.sh | tee "$GITHUB_WORKSPACE/evaluation.txt"
+EXIT_CODE=${PIPESTATUS[0]}
+exit $EXIT_CODE

frooky-0.2.1/.github/scripts/prepare-artifacts.sh

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Usage: prepare-artifacts.sh <platform>
+# Example: prepare-artifacts.sh android
+
+PLATFORM="${1:-}"
+
+if [ -z "$PLATFORM" ]; then
+  echo "Error: Platform argument required (android or ios)"
+  exit 1
+fi
+
+RESULTS_DIR="${PLATFORM}-test-results"
+EXAMPLE_DIR="docs/examples/${PLATFORM}-app"
+
+mkdir -p "$RESULTS_DIR"
+
+# Copy files from example directory
+cd "$EXAMPLE_DIR"
+for file in auto.log frooky.log output.json before.png after.png; do
+  cp "$file" "$GITHUB_WORKSPACE/$RESULTS_DIR/" 2>/dev/null || true
+done
+cp -r tmp "$GITHUB_WORKSPACE/$RESULTS_DIR/" 2>/dev/null || true
+cd "$GITHUB_WORKSPACE"
+
+# Copy maestro log from most recent test run
+LATEST_TEST=$(find ~/.maestro/tests -type f -name "maestro.log" 2>/dev/null | head -1)
+if [ -n "$LATEST_TEST" ]; then
+  cp "$LATEST_TEST" "$RESULTS_DIR/maestro.log"
+fi
+
+echo "Artifacts prepared in $RESULTS_DIR/"

frooky-0.2.1/.github/workflows/build.yml

@@ -0,0 +1,37 @@
+name: Build Python Package
+
+on:
+  workflow_call:
+    outputs:
+      artifact-name:
+        description: "Name of the uploaded artifact"
+        value: ${{ jobs.build.outputs.artifact-name }}
+
+jobs:
+  build:
+    permissions:
+      contents: read
+    runs-on: ubuntu-latest
+    outputs:
+      artifact-name: ${{ steps.upload.outputs.artifact-name }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Fetch all history and tags for setuptools-scm
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "24"
+          cache: 'npm'
+          cache-dependency-path: './frooky/agent/package-lock.json'
+      - run: chmod +x compileAgent.sh
+      - run: ./compileAgent.sh --prod
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+      - run: python -m pip install --upgrade build
+      - run: python -m build
+      - uses: actions/upload-artifact@v4
+        id: upload
+        with:
+          name: dist
+          path: dist/*

frooky-0.2.1/.github/workflows/publish.yml

@@ -0,0 +1,30 @@
+name: Publish Python Package
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    permissions:
+      contents: read
+    uses: ./.github/workflows/build.yml
+
+  verify-build:
+    needs: [build]
+    permissions:
+      contents: read
+    uses: ./.github/workflows/test-build.yml
+
+  publish:
+    runs-on: ubuntu-latest
+    needs: [build, verify-build]
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: ${{ needs.build.outputs.artifact-name }}
+          path: .
+      - uses: pypa/gh-action-pypi-publish@release/v1

frooky-0.2.1/.github/workflows/test-android-runtime.yml

@@ -0,0 +1,134 @@
+name: Test Android Runtime
+
+on:
+  workflow_call:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install frooky from wheel
+        run: pip install dist/*.whl
+
+      - name: Install Maestro
+        run: |
+          curl -Ls "https://get.maestro.mobile.dev" | bash
+          echo "${HOME}/.maestro/bin" >> $GITHUB_PATH
+
+      # - name: Set up JDK 17
+      #   uses: actions/setup-java@v4
+      #   with:
+      #     java-version: '17'
+      #     distribution: 'temurin'
+
+      # - name: Setup Gradle
+      #   uses: gradle/actions/setup-gradle@v4
+
+      # - name: Clone mas-app-android repository
+      #   uses: actions/checkout@v4
+      #   with:
+      #     repository: cpholguera/mas-app-android
+      #     path: mas-app-android
+
+      # - name: Copy example files and build APK
+      #   run: |
+      #     EXAMPLE_DIR="docs/examples/android-app"
+
+      #     # Copy MastgTest.kt if it exists
+      #     if [ -f "$EXAMPLE_DIR/MastgTest.kt" ]; then
+      #       cp -f "$EXAMPLE_DIR/MastgTest.kt" mas-app-android/app/src/main/java/org/owasp/mastestapp/MastgTest.kt
+      #       echo "Copied MastgTest.kt"
+      #     fi
+
+      #     # Copy build.gradle.kts.libs if it exists
+      #     if [ -f "$EXAMPLE_DIR/build.gradle.kts.libs" ]; then
+      #       sed -i '/\/\/ ADD_LIBS_HERE/{
+      #         r '"$EXAMPLE_DIR/build.gradle.kts.libs"'
+      #         d
+      #       }' mas-app-android/app/build.gradle.kts
+      #       echo "Replaced libs in build.gradle.kts"
+      #     fi
+
+      #     # Build the APK
+      #     cd mas-app-android
+      #     ./gradlew assembleDebug --stacktrace
+      #     echo "Build succeeded"
+
+      - name: Enable KVM
+        run: |
+          echo 'KERNEL=="kvm", GROUP="kvm", MODE="0666", OPTIONS+="static_node=kvm"' | sudo tee /etc/udev/rules.d/99-kvm4all.rules
+          sudo udevadm control --reload-rules
+          sudo udevadm trigger --name-match=kvm
+
+      - name: Start Android Emulator and Run Tests
+        uses: reactivecircus/android-emulator-runner@v2
+        with:
+          api-level: 34
+          target: google_apis
+          arch: x86_64
+          emulator-options: -wipe-data -no-snapshot-save -no-snapshot-load -no-window -gpu swiftshader_indirect -noaudio -no-boot-anim
+          disable-animations: true
+          script: |
+
+            chmod +x .github/scripts/android/prep-device.sh
+            .github/scripts/android/prep-device.sh
+
+            chmod +x .github/scripts/android/install-frida-server.sh
+            .github/scripts/android/install-frida-server.sh
+
+            # Install the app APK
+            cd docs/examples/android-app && unzip -o MASTG-DEMO-0060.apk.zip && adb install -r MASTG-DEMO-0060.apk
+
+            # adb install mas-app-android/app/build/outputs/apk/debug/app-debug.apk
+
+            # Run the testing script
+            cd docs/examples/android-app && chmod +x auto.sh && ./auto.sh
+
+      # - name: Upload APK
+      #   uses: actions/upload-artifact@v4
+      #   with:
+      #     name: MASTestApp.apk
+      #     path: mas-app-android/app/build/outputs/apk/debug/app-debug.apk
+
+      - name: Prepare artifacts for upload
+        if: always()
+        run: |
+          chmod +x .github/scripts/prepare-artifacts.sh
+          .github/scripts/prepare-artifacts.sh android
+
+      - name: Evaluate Test Results
+        if: always()
+        run: |
+          chmod +x .github/scripts/evaluate-results.sh
+          .github/scripts/evaluate-results.sh android
+
+      - name: Create Job Summary
+        if: always()
+        run: |
+          chmod +x .github/scripts/create-job-summary.sh
+          .github/scripts/create-job-summary.sh android >> $GITHUB_STEP_SUMMARY
+
+      - name: Upload Dynamic Test Artifacts
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: android-dynamic-test-results
+          path: android-test-results/*

frooky-0.2.1/.github/workflows/test-build.yml

@@ -0,0 +1,39 @@
+name: Verify Build
+
+on:
+  workflow_call:
+
+permissions:
+  contents: read
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist
+
+      - name: Check build artifacts
+        run: |
+          ls -lh dist/
+          test -f dist/*.whl
+          test -f dist/*.tar.gz
+
+      - name: Test install from wheel
+        run: |
+          python -m pip install dist/*.whl
+          frooky --help
+
+      - name: Verify agent artifacts in wheel
+        run: |
+          unzip -l dist/*.whl | grep "frooky/agent/dist/agent-android.js"
+          unzip -l dist/*.whl | grep "frooky/agent/dist/agent-ios.js"
+          echo "All agent artifacts present in wheel"