Perseus Shield Android

Forensic & migration toolkit for Android devices

A collection of PowerShell tools that give you full visibility into what's on your Android phone — what's been installed, what's been used, and what shouldn't be there.

This repository contains two tools:

Tool	Purpose
phone-forensics.ps1	Post-confiscation forensic scanner — detects spyware, sideloaded apps, and tampered APKs
app-usage-report.ps1	App usage analyzer — ranks every app by actual usage time for migration, audits, and digital detox

Both tools use the same setup: ADB on Windows, USB debugging on the phone, no root required, no app installation on the device, fully read-only operations.

---

Tool 1: phone-forensics.ps1

Post-confiscation forensic scanner for Android devices

Your phone was taken by border agents, security services, or law enforcement and returned to you. What did they install? Perseus Shield tells you in minutes.

What This Tool Does

• Scans all apps installed since a specific date (e.g., the day your phone was confiscated)
• Identifies apps that were sideloaded (not from any app store)
• Cross-references every app against Google Play Store to verify legitimacy
• Checks for known spyware signatures : Pegasus (NSO Group), Predator (Intellexa), Monokle (FSB), Hermit (RCS Lab), NoviSpy, FinFisher, Candiru, QuaDream, Paragon Graphite, and 15+ stalkerware families
• Computes SHA-256 hashes and generates VirusTotal lookup links
• Performs a full permission audit with danger classification per permission
• Detects if VK Store (RuStore) was used to silently install additional apps
• Recognizes 70+ system package prefixes to eliminate false positives
• Produces color-coded terminal output and 4 export files (report, verdicts, permissions, CSV)

Who Is This For

• Journalists crossing borders of authoritarian states
• Business travelers whose phones were inspected at border crossings
• Activists and NGO workers in countries with state surveillance
• Anyone whose phone was in custody of security services (FSB, police, border agents)
• Security researchers analyzing post-confiscation device integrity

---

Tool 2: app-usage-report.ps1

App usage analyzer — find out what you actually use

Migrating to a new phone? Doing a digital detox? Auditing your subscriptions? This tool extracts real usage statistics from your device and ranks every app by total time used, last access date, and launch count.

What This Tool Does

• Pulls usage statistics directly from Android's dumpsys usagestats
• Filters apps used within a configurable time window (default 90 days)
• Ranks every app by total time used
• Shows last used date in human-friendly format ("3 days ago", "2 weeks ago")
• Counts how many times each app was launched
• Groups apps into 4 tiers: TOP 10 (Daily Drivers), FREQUENT , REGULAR , OCCASIONAL
• Generates a beautiful interactive HTML dashboard with clickable migration checkboxes
• Also exports CSV for spreadsheets and TXT for plain-text checklists
• Recognizes 80+ common apps and shows their friendly names

Who Is This For

• Anyone migrating to a new Android phone (Samsung Smart Switch is great, but it copies everything — this tells you what's worth keeping)
• People auditing screen time and digital wellbeing
• Subscription cleanup — find paid apps you haven't opened in 90 days
• Privacy audits — apps you don't use still have permissions to your data
• Home screen Marie Kondo session — does it get used?

---

What You Need (For Both Tools)

1. A Windows 10 or 11 computer (laptop or desktop)
2. A USB cable that connects your Android phone to the computer
3. Your Android phone with Android 4.4 or newer
4. About 10-20 minutes of time

That's it. No special software knowledge required. Follow the steps below exactly.

---

Step 1: Download ADB (Android Debug Bridge)

ADB is a free tool from Google that lets your computer talk to your Android phone.

1. Open your web browser on your computer
2. Go to: https://developer.android.com/tools/releases/platform-tools
3. Click "Download SDK Platform-Tools for Windows"
4. Check the box to accept the terms and click "Download"
5. A file called platform-tools-latest-windows.zip will download
6. Find the downloaded file (usually in your Downloads folder)
7. Right-click the zip file and select "Extract All..."
8. Click "Extract"
9. You now have a folder called platform-tools-latest-windows with a subfolder platform-tools inside it

Remember this folder location. For example:

C:\Users\YourName\Downloads\platform-tools-latest-windows\platform-tools\

Inside you should see files including adb.exe, fastboot.exe, and others.

---

Step 2: Download Perseus Shield Tools

1. Download the files phone-forensics.ps1 and app-usage-report.ps1 from this GitHub repository
2. Move both files into the platform-tools folder from Step 1

So the files should be at:

C:\Users\YourName\Downloads\platform-tools-latest-windows\platform-tools\phone-forensics.ps1
C:\Users\YourName\Downloads\platform-tools-latest-windows\platform-tools\app-usage-report.ps1

They must be in the same folder as adb.exe.

---

Step 3: Enable Developer Mode on Your Phone

Your phone has a hidden "Developer Mode" that needs to be turned on. This is safe and does not void your warranty.

For Samsung phones:

1. Open Settings
2. Scroll down and tap "About phone"
3. Tap "Software information"
4. Find "Build number"
5. Tap "Build number" 7 times quickly
6. You will see a message: "You are now a developer!"
7. If asked, enter your phone's PIN/password

For Xiaomi / POCO / Redmi phones:

1. Open Settings
2. Tap "About phone"
3. Find "MIUI version" (or "HyperOS version")
4. Tap it 7 times quickly
5. You will see: "You are now a developer!"

For Google Pixel phones:

1. Open Settings
2. Tap "About phone"
3. Find "Build number"
4. Tap it 7 times quickly

For OnePlus phones:

1. Open Settings
2. Tap "About device"
3. Find "Build number"
4. Tap it 7 times quickly

For Huawei / Honor phones:

1. Open Settings
2. Tap "About phone"
3. Find "Build number"
4. Tap it 7 times quickly

---

Step 4: Enable USB Debugging

Now you need to turn on USB Debugging. This allows your computer to communicate with your phone.

For Samsung phones:

1. Open Settings
2. Scroll down to "Developer options" (it's now visible after Step 3)
3. Tap "Developer options"
4. Scroll down to "USB debugging"
5. Toggle it ON
6. Tap "OK" on the warning popup

For Xiaomi / POCO / Redmi phones:

1. Open Settings
2. Tap "Additional settings"
3. Tap "Developer options"
4. Scroll down to "USB debugging"
5. Toggle it ON
6. Tap "OK" on the warning popup
7. ALSO toggle on "Install via USB" (scroll down to find it)

For Google Pixel / OnePlus / other phones:

1. Open Settings
2. Tap "System"
3. Tap "Developer options"
4. Scroll down to "USB debugging"
5. Toggle it ON
6. Tap "OK" on the warning popup

---

Step 5: Connect Your Phone to the Computer

1. Plug your USB cable into your phone and your computer
2. On your phone, you may see a popup asking about the USB connection mode
3. Select "File Transfer" or "MTP" (not "Charging only")
4. You may see a popup asking "Allow USB debugging?"
5. Check "Always allow from this computer"
6. Tap "Allow"

Important: If you don't see the "Allow USB debugging" popup, it will appear when you first run an ADB command. Don't worry, just continue to the next step.

---

Step 6: Open PowerShell

1. On your computer, press the Windows key on your keyboard
2. Type powershell
3. Click "Windows PowerShell" (you can use regular, not Administrator)
4. A blue/black terminal window will open
5. Navigate to the platform-tools folder by typing:

cd C:\Users\YourName\Downloads\platform-tools-latest-windows\platform-tools

Replace YourName with your actual Windows username. If you're not sure, type whoami in PowerShell and it will show you.

6. Verify you're in the right folder by typing:

ls

You should see adb.exe, phone-forensics.ps1, and app-usage-report.ps1 in the list.

---

Step 7: Verify Phone Connection

Before running anything, let's make sure your computer can see your phone.

1. In PowerShell, type:

.\adb devices

2. Look at your phone screen - you may see the "Allow USB debugging?" popup now. Tap "Allow" .

3. Run the command again:

.\adb devices

4. You should see something like:

List of devices attached
ABCD1234XYZ     device

If you see device next to a serial number, you're connected.

If you see unauthorized , check your phone for the Allow popup and tap Allow.

If you see nothing (empty list), try:

• Unplug and replug the USB cable
• Try a different USB cable (some cables are charge-only and don't transfer data)
• Make sure USB debugging is ON (Step 4)
• Make sure your phone is set to "File Transfer" mode (Step 5)

---

Step 8: Allow Script Execution

Before running any of the tools, allow the scripts to execute:

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

This is safe — it only applies to this one PowerShell window and resets when you close it.

You only need to run this once per PowerShell session.

---

Running phone-forensics.ps1 (Forensic Scanner)

Scan from a specific date (recommended if you know when your phone was taken):

.\phone-forensics.ps1 -FromDate "2026-03-28"

Replace 2026-03-28 with the actual date your phone was confiscated , in YYYY-MM-DD format.

Scan ALL apps on the phone:

.\phone-forensics.ps1 -FromDate "2009-01-01"

Warning: A full scan of all apps takes 10-20 minutes. A date-specific scan takes 2-5 minutes.

Scan without Google Play Store checks (offline / no internet):

.\phone-forensics.ps1 -FromDate "2026-03-28" -SkipPlayCheck

Scan with VirusTotal auto-lookup (optional):

First, get a free API key from https://www.virustotal.com/gui/join-us

.\phone-forensics.ps1 -FromDate "2026-03-28" -VTApiKey "your_api_key_here"

Note: The free VirusTotal API allows 4 requests per minute. This makes the scan much slower but gives you malware detection results from 70+ antivirus engines.

Reading the Forensic Results

The scan shows results in real-time in the terminal with color coding:

Tag	Verdict	Meaning	Action
[!!!]	SPYWARE	Matches known spyware database	Stop using phone. Factory reset immediately.
[!! ]	DANGEROUS	Sideloaded + high permissions + not on Play Store	Investigate and likely remove
[ ! ]	SUSPICIOUS	Unexpected source or permissions	Review manually
[ ~ ]	LEGITIMATE	Known app, minor flags	Probably safe
[ OK]	SAFE	Verified on Play Store, from official source	No action needed
[SYS]	SYSTEM	OS or manufacturer component	Do not touch

Forensic Output Files

The scan creates 4 files in the same folder:

File	What It Contains
forensic-report_*.txt	Full detailed report with all findings
forensic-verdicts_*.txt	One-line-per-app verdict summary (quick review)
forensic-permissions_*.txt	Full permission audit for every non-system app
forensic-apps_*.csv	Spreadsheet you can open in Excel with all data

---

Running app-usage-report.ps1 (Usage Analyzer)

Default scan (last 90 days):

.\app-usage-report.ps1

Custom time window:

.\app-usage-report.ps1 -DaysBack 30

.\app-usage-report.ps1 -DaysBack 180

Reading the Usage Report

The script automatically opens an HTML report in your browser with apps grouped into four tiers:

Tier	Range	Meaning
TOP 10	Apps #1-10	Your daily drivers — migrate first
FREQUENT	Apps #11-25	Frequent use — migrate next
REGULAR	Apps #26-50	Regular use — migrate if needed
OCCASIONAL	Apps #51+	Occasional use — consider if you really need them

Each app card shows:

• Total time used in the period
• When it was last opened
• How many times it was launched
• A clickable checkbox to mark as migrated

Usage Output Files

The scan creates 3 files in the same folder:

File	What It Contains
app-usage-report_*.html	Interactive visual dashboard with checkboxes
app-usage-report_*.csv	Spreadsheet for Excel/Google Sheets
app-usage-report_*.txt	Plain text checklist for terminal/Notepad

---

What To Do If The Forensic Scanner Finds Threats

If you see SPYWARE:

1. STOP using the phone immediately — do not enter any passwords
2. Do NOT try to uninstall the spyware — preserve evidence first
3. Take screenshots of the scan results
4. Factory reset the phone from Settings or Recovery Mode
5. Change ALL passwords from a different, clean device
6. Contact for help:
   • Access Now Digital Security Helpline : security@accessnow.org
   • Amnesty International Security Lab : https://securitylab.amnesty.org
   • Citizen Lab : https://citizenlab.ca

If you see DANGEROUS:

1. Check if you installed the app yourself
2. If NOT, remove it:

.\adb shell "pm uninstall com.example.suspicious.app"

Replace com.example.suspicious.app with the actual package name from the report.

3. Check the VirusTotal link in the report for malware detections
4. Consider factory reset if the app was installed while your phone was confiscated

If you see SUSPICIOUS:

1. Review the app — do you recognize it? Did you install it?
2. Check when it was installed — does the date match when your phone was in someone else's possession?
3. Click the VirusTotal link to check the hash
4. If unsure, remove it with the uninstall command above

---

How To Remove an App Using ADB

If you find an app that needs to be removed:

.\adb shell "pm uninstall com.example.app.package.name"

You should see Success as the response.

To verify it was removed:

.\adb shell "pm list packages" | Select-String "example"

If nothing comes back, the app is gone.

---

Turning Off Developer Mode After Scanning

When you're done scanning, you can turn off Developer Mode:

1. Open Settings on your phone
2. Go to Developer options
3. Toggle the switch at the top to OFF
4. This disables USB debugging and all developer features

---

Understanding False Positives

The forensic scanner may flag some apps as HIGH or SUSPICIOUS that are actually safe. Common false positives include:

• System apps from your phone manufacturer (Samsung, Xiaomi, etc.) — these show as "sideloaded" because they come pre-installed in firmware, not from the Play Store
• Carrier-branded apps (Vodafone, Orange, T-Mobile setup wizards) — pre-installed by your mobile carrier
• Factory test tools (fingerprint sensor tests, hardware diagnostics) — leftover tools from manufacturing

The scanner handles most of these automatically by recognizing 70+ system package prefixes and treating factory-date apps (2009-01-01) as system components. If you see a SUSPICIOUS verdict on an app installed at 2009-01-01, it's almost certainly a system component.

---

Known Spyware Database

Perseus Shield checks for signatures from these known threats:

Threat	Developer	Known Targets
Pegasus	NSO Group (Israel)	Journalists, activists, heads of state
Predator	Intellexa/Cytrox (EU)	Politicians, journalists
Monokle	Special Technology Center (Russia/FSB)	Russian citizens, Ukrainian supporters
Hermit	RCS Lab (Italy)	Activists in Italy, Kazakhstan
NoviSpy	Serbian BIA	Serbian civil society
FinFisher/FinSpy	Gamma Group (Germany)	Activists worldwide
Candiru/DevilsTongue	Candiru (Israel)	Journalists, activists
Reign	QuaDream (Israel)	Civil society
Graphite	Paragon Solutions (Israel)	Journalists in EU
Android.Backdoor.916	Unknown (Russia-linked)	Russian business executives
+ 15 stalkerware families	Various	Domestic abuse victims

---

Frequently Asked Questions

Are these tools safe to run?

Yes. Both scripts only read data from your phone. They do not modify, delete, or install anything. They use adb shell dumpsys (which reads metadata) and adb shell sha256sum (which computes file hashes). These are read-only operations.

Do these tools work on all Android phones?

They work on any Android phone that supports USB debugging (Android 4.4 and above, which covers virtually all phones made after 2013).

Do these tools work on iPhones?

No. These tools are for Android only. For iPhones, use iVerify Basic ($0.99 on the App Store) which can detect Pegasus and other commercial spyware.

Do I need internet for the scans?

The forensic scanner works offline with the -SkipPlayCheck flag. Without that flag, it queries Google Play Store to verify each app exists. The usage report is fully offline.

How long does each scan take?

phone-forensics.ps1 : 2-5 minutes for date-specific scans, 10-20 minutes for full device scans, much longer with VirusTotal API enabled.

app-usage-report.ps1 : 1-2 minutes regardless of time window.

Can spyware detect that I'm scanning?

Standard spyware cannot detect ADB-based scanning. The scans read package metadata and usage stats, not app data. However, very sophisticated implants (like Pegasus) that operate at the kernel level could theoretically detect ADB connections. If you suspect Pegasus-level compromise, contact Amnesty Security Lab or Citizen Lab directly.

What if the forensic scanner says everything is clean but I still feel unsafe?

Package-level scanning cannot detect certain advanced threats like kernel-level rootkits, modified system partitions, or zero-day exploits that don't install visible packages. If your phone was in custody of a technically sophisticated adversary (FSB, NSA, MSS, etc.), consider:

1. Running MVT (Amnesty International's Mobile Verification Toolkit) for deeper analysis
2. Running iVerify Basic on the device for complementary scanning
3. Factory resetting the phone as the most reliable remediation
4. Using a new phone for sensitive communications

Why does the usage report show "0h" or weird timing?

If you see all zero values, your Samsung uses bucketed usage stats with lastTimeComponentUsed instead of lastTimeUsed. The current version of app-usage-report.ps1 handles this correctly. If you have an older version, redownload it from this repository.

Can I use the usage report for digital detox?

Absolutely. Run it weekly or monthly to track which apps consume your time. It's also great for subscription cleanup — if you haven't opened a paid app in 90 days, why are you still paying for it?

---

Complementary Tools

Tool	Type	Cost	Best For
iVerify Basic	Mobile app (Android/iOS)	$0.99	Pegasus/zero-day detection
MVT	Command line (Linux/Mac)	Free	Deep forensic analysis
Certo AntiSpy	Mobile app (Android)	Free/Paid	Stalkerware detection
Anti Spy Detector	Mobile app (Android)	Free/Paid	General spyware scanning
Samsung Smart Switch	Mobile app	Free	Phone migration (data + apps)
Google Digital Wellbeing	Built-in (Android)	Free	Live screen time monitoring

Perseus Shield tools are designed to complement these, not replace them. The forensic scanner fills a specific gap: fast, transparent, post-confiscation triage with date-specific filtering. The usage report gives you offline, exportable, hash-stable data you can keep for records.

---

Roadmap

• v1 (current) — PowerShell + ADB for Windows
• v2 (next) — Docker container with Python engine and web UI (cross-platform)
• v3 (future) — Native Android app with real-time permission monitoring

---

Disclaimer

These tools are provided for defensive security purposes only . They are designed to help individuals determine the state of their personal devices. The authors do not provide legal advice. If you believe your rights were violated during a device search, consult a qualified attorney in your jurisdiction.

The spyware signature database is based on public research from Citizen Lab, Amnesty International Security Lab, Lookout, Google Threat Analysis Group (TAG), and other reputable sources. It may not detect previously unknown (zero-day) spyware or custom-built implants.

---

Contributing

Contributions welcome. Priority areas:

• Additional spyware IOC signatures
• Expanded system package prefix database for more phone brands
• Translations of the README into other languages (Russian, Arabic, Farsi, Chinese)
• Docker containerized version with web UI
• macOS/Linux support
• Additional friendly app names for the usage report

---

Credits

• Citizen Lab (University of Toronto) — Monokle spyware research and IOCs
• Amnesty International Security Lab — MVT toolkit and Pegasus research
• Lookout Mobile Security — Original Monokle analysis
• Google Threat Analysis Group — Commercial spyware tracking
• iVerify / Trail of Bits — Mobile threat hunting research
• Access Now — Digital security helpline for at-risk individuals

---

License

MIT License. See LICENSE file for details.

Free to use, modify, and distribute. If these tools help you, consider donating to Access Now or Citizen Lab who do critical work protecting people from surveillance.