Cyrus

Cyrus is a Linux-based Android APK security lab workflow for authorized testing and research. It wraps a sequence of common Android assessment tasks into a menu-driven Bash interface: decompiling an APK, generating a controlled Android Meterpreter payload, merging payload components into a decompiled APK, rebuilding an unsigned artifact, and launching a matching Metasploit handler.

The project is intentionally small and inspectable. Each major operation lives in a separate shell module under modules/, so the workflow can be audited, modified, or run step-by-step without hiding the underlying tooling.

Cyrus is for owned devices, lab environments, internal security validation, training, and engagements where you have explicit written authorization. Do not use it against third-party apps, devices, accounts, networks, or users without permission.

Table of Contents

• What Cyrus Does
• Safety and Authorization
• Repository Layout
• How the Workflow Fits Together
• Requirements
• Setup
• Usage
• Outputs
• Signing the Rebuilt APK
• Network and Handler Notes
• Troubleshooting
• Current Limitations
• Credits

What Cyrus Does

Cyrus automates the repetitive mechanics of an authorized Android APK payload lab:

• Scans APPS/ for APK files and decompiles the selected target with apktool.
• Generates a Metasploit Android payload APK using operator-provided LHOST and LPORT values.
• Decompiles the generated payload and copies the com/metasploit/stage smali package into the target APK tree.
• Merges payload permissions from the payload manifest into the target manifest when they are not already present.
• Adds the payload service and boot receiver components to the target manifest.
• Attempts to patch the target launcher activity so the payload service is started from onCreate() when compatible smali structure is found.
• Optionally renames the payload package from com/metasploit to a validated com/<suffix> namespace.
• Rebuilds the modified APK to output/unsigned.apk.
• Starts a matching Metasploit multi-handler from the menu.
• Provides a cleanup action that resets generated output.

Cyrus does not sign APKs, install Android platform tools, install Metasploit, install apktool, generate keystores, or guarantee payload execution on every Android version or app structure.

Safety and Authorization

Use Cyrus only in contexts where you can clearly prove authorization:

• personal lab devices
• internally owned test applications
• training ranges
• sanctioned penetration tests
• bug bounty targets where the exact activity is in scope and allowed

Before using Cyrus, confirm:

• the APK and device are yours or explicitly approved for testing
• the network path between the Android device and handler is authorized
• the generated artifact will not be distributed outside the test environment
• any findings are reported through the appropriate internal, client, or program process

This repository is provided for educational and defensive security research. You are responsible for complying with local law, program rules, client agreements, and platform policies.

Repository Layout

Cyrus/
├── APPS/                         # User-created input directory for test APKs
├── output/                       # Generated working directory, rebuilt artifacts, payload files
├── modules/
│   ├── decompile.sh              # APK selection and apktool decompile step
│   ├── generate_payload.sh       # msfvenom Android payload generation
│   ├── inject.sh                 # smali copy, manifest merge, launcher hook attempt
│   ├── encode.sh                 # package rename / smali namespace rewrite
│   ├── rebuild.sh                # apktool rebuild to output/unsigned.apk
│   ├── metasploit.sh             # Metasploit handler launch
│   ├── cleanup.sh                # output directory reset
│   ├── antivirus_killer.sh       # legacy/experimental module, not loaded by cyrus.sh
│   └── obfuscapk.sh              # local Obfuscapk integration draft, not loaded by cyrus.sh
├── cyrus.sh                      # Main interactive menu
├── Con2.gif                      # Demo animation retained for the project README
├── preview.png                   # Static preview asset
└── Screenshot From 2025-10-09 12-27-13.png

APPS/ and output/ may not exist in a fresh clone. Cyrus creates output/ automatically. Create APPS/ when you are ready to add lab APKs.

How the Workflow Fits Together

Cyrus is a wrapper around proven external tools rather than a custom Android build system.

Stage	Menu Action	Main Module	Primary External Tooling	Result
1	Decompile APK	modules/decompile.sh	apktool	Target APK expanded into output/decompiled_apk/
2	Generate Payload	modules/generate_payload.sh	msfvenom	Payload APK written to output/payload.apk
3	Inject Payload	modules/inject.sh	apktool, shell tools	Payload smali and manifest entries merged into target tree
4	Obfuscate Payload	modules/encode.sh	shell tools	com/metasploit references renamed to com/<suffix>
5	Rebuild APK	modules/rebuild.sh	apktool, Java runtime	Unsigned APK written to output/unsigned.apk
6	Launch Metasploit	modules/metasploit.sh	msfconsole	Matching handler starts with chosen host/port
7	Cleanup	modules/cleanup.sh	shell tools	Generated output is removed and recreated

The workflow is intentionally sequential. Run the steps in order unless you are debugging a specific stage.

Requirements

Cyrus is designed for Linux environments such as Kali, Debian, Ubuntu, or similar distributions.

Required command-line tools:

• bash
• apktool
• java
• msfvenom
• msfconsole
• find, awk, sed, grep, cp, mv, and standard GNU/Linux shell utilities

Recommended runtime versions:

• OpenJDK 11 or 17
• current Kali/Debian-packaged Metasploit Framework
• Apktool 2.8.x or newer

Verify your environment:

apktool -version
java -version
msfvenom --version
msfconsole --version

Setup

Clone the repository:

git clone git@github.com:Clock-Skew/Cyrus.git
cd Cyrus

Make the launcher executable if needed:

chmod +x cyrus.sh

Create the input directory for lab APKs:

mkdir -p APPS

Place authorized test APKs in APPS/.

Start Cyrus:

./cyrus.sh

Usage

Use the menu from top to bottom:

1. Decompile APK
2. Generate Payload
3. Inject Payload
4. Obfuscate Payload (smali rename)
5. Rebuild APK (Unsigned)
6. Launch Metasploit
7. Cleanup
8. Exit

Recommended operator flow:

1. Add one authorized APK to APPS/.
2. Run ./cyrus.sh.
3. Decompile the APK and confirm output/decompiled_apk/ is created.
4. Generate the payload with a device-reachable LHOST and selected LPORT.
5. Inject the payload into the decompiled APK.
6. Optionally rename the payload package with a lowercase suffix such as cyrus_lab.
7. Rebuild the APK.
8. Sign the resulting output/unsigned.apk using your own signing workflow.
9. Start the handler and test only inside the authorized environment.

Outputs

Common generated paths:

output/
├── decompiled_apk/     # Decompiled target APK tree
├── payload.apk         # Generated Android payload APK
├── payload_smali/      # Decompiled payload APK tree
└── unsigned.apk        # Rebuilt unsigned target APK

Generated output is disposable. Use the cleanup menu option to reset the workspace before a fresh run.

Signing the Rebuilt APK

Cyrus stops at output/unsigned.apk. Android generally requires a signed APK before installation.

Use a signing workflow appropriate for your lab. Example commands if the tools and keystore already exist:

apksigner sign --ks debug.keystore --ks-key-alias androiddebugkey \
  --ks-pass pass:android --key-pass pass:android output/unsigned.apk

apksigner verify output/unsigned.apk

Legacy jarsigner workflows may work for older test conditions, but apksigner is the preferred Android signing tool.

Network and Handler Notes

LHOST and LPORT must line up between the generated payload and handler.

For same-LAN testing:

• use the host machine’s LAN IP as the payload LHOST
• use the same LPORT when launching the Metasploit handler
• confirm the Android test device can reach the host on that port

For routed or VPN lab testing:

• use an address the Android test device can reach from its network position
• account for firewall rules, NAT, VPN routing, and port forwarding
• regenerate the payload if the payload callback address changes

Keep handler exposure as narrow as possible and do not leave listeners running after the test.

Troubleshooting

No APKs are listed

Create APPS/ and place at least one .apk file inside it.

mkdir -p APPS

Dependency checks fail

Install or fix the missing tool before continuing. Cyrus reports missing apktool, msfvenom, or java during startup but does not install packages for you.

Injection fails because payload files are missing

Run the steps in order. Inject Payload expects:

• output/decompiled_apk/AndroidManifest.xml
• output/payload.apk

Rebuild fails with manifest errors

Start from a clean output tree and rerun the workflow. XML merge issues are usually caused by an incompatible manifest state or a previous partial run.

Rebuild fails with smali errors after package rename

Use a safe package suffix:

• lowercase letters
• digits
• underscores
• must not begin with a digit

Example: cyrus_lab

Handler starts but no session appears

Check:

• payload LHOST is reachable from the Android test device
• payload LPORT matches the handler port
• host firewall allows inbound traffic on the chosen port
• the app was launched after installation
• the test device and host are on the expected network path

Current Limitations

• Cyrus does not sign rebuilt APKs.
• Cyrus does not install dependencies.
• Cyrus does not guarantee compatibility with every APK, Android version, resource table, or launcher activity structure.
• The launcher auto-start patch intentionally skips some smali patterns rather than forcing unsafe edits.
• antivirus_killer.sh is legacy/experimental and is not loaded by cyrus.sh.
• obfuscapk.sh is a local integration draft with machine-specific paths and is not loaded by cyrus.sh.
• No formal automated test suite is currently included.

Development Notes

The project is deliberately simple Bash. When making changes:

• keep modules small and readable
• preserve clear precondition checks
• avoid hiding tool output that helps troubleshooting
• keep generated files under output/
• avoid committing APKs, payloads, keystores, private client files, or generated artifacts
• keep the numbered usage steps in sync with the live menu when you change module order or labels

Useful checks before committing:

bash -n cyrus.sh modules/*.sh
git status --short

Credits

• Inspired by backdoor-apk by dana-at-cp.
• Built on top of Apktool by iBotPeaches and contributors.
• Uses Metasploit Framework tooling by Rapid7 and the community.
• Thanks to the broader Android reverse-engineering and security research ecosystem.

License

No license file is currently included. Until a license is added, all rights are reserved by default.