Skip to content

Commit 8b2a0c8

Browse files
PixelCode01PixelCode01
committed
Add comprehensive security documentation and false positive mitigation
1 parent 239841d commit 8b2a0c8

File tree

4 files changed

+218
-2
lines changed

4 files changed

+218
-2
lines changed

‎.github/workflows/build-release.yml‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -163,6 +163,41 @@ jobs:
163163
echo "Release files prepared:"
164164
ls -la release/
165165
166+
- name: Generate file hashes
167+
run: |
168+
cd release
169+
echo "# File Verification Hashes" > HASHES.md
170+
echo "" >> HASHES.md
171+
echo "Use these SHA256 hashes to verify file integrity:" >> HASHES.md
172+
echo "" >> HASHES.md
173+
174+
for file in *; do
175+
if [ -f "$file" ] && [ "$file" != "HASHES.md" ]; then
176+
hash=$(sha256sum "$file" | cut -d' ' -f1)
177+
size=$(stat -c%s "$file")
178+
echo "**$file**" >> HASHES.md
179+
echo "- SHA256: \`$hash\`" >> HASHES.md
180+
echo "- Size: $(printf "%'d" $size) bytes" >> HASHES.md
181+
echo "" >> HASHES.md
182+
fi
183+
done
184+
185+
echo "## How to verify:" >> HASHES.md
186+
echo "" >> HASHES.md
187+
echo "**Windows (PowerShell):**" >> HASHES.md
188+
echo "\`\`\`powershell" >> HASHES.md
189+
echo "Get-FileHash -Algorithm SHA256 android-bloatware-remover-windows.exe" >> HASHES.md
190+
echo "\`\`\`" >> HASHES.md
191+
echo "" >> HASHES.md
192+
echo "**Linux/Mac:**" >> HASHES.md
193+
echo "\`\`\`bash" >> HASHES.md
194+
echo "sha256sum android-bloatware-remover-linux" >> HASHES.md
195+
echo "shasum -a 256 android-bloatware-remover-macos" >> HASHES.md
196+
echo "\`\`\`" >> HASHES.md
197+
198+
echo "Generated hashes:"
199+
cat HASHES.md
200+
166201
- name: Create Release
167202
uses: softprops/action-gh-release@v2
168203
env:
@@ -175,10 +210,14 @@ jobs:
175210
176211
Standalone executables for Windows, Linux, and macOS.
177212
213+
### ⚠️ Windows Defender False Positive
214+
Windows Defender may flag the executable as a virus. This is a **false positive** common with PyInstaller executables. The tool is completely safe - all source code is open and auditable. See [SECURITY.md](https://github.com/PixelCode01/UIBloatwareRegistry/blob/main/SECURITY.md) for details and solutions.
215+
178216
### Download Instructions:
179217
- **Windows**: Download `android-bloatware-remover-windows.exe`
180218
- **Linux**: Download `android-bloatware-remover-linux`
181219
- **macOS**: Download `android-bloatware-remover-macos`
220+
- **Verification**: Download `HASHES.md` to verify file integrity
182221
183222
### Usage:
184223
1. Download the appropriate executable for your operating system
@@ -201,6 +240,14 @@ jobs:
201240
202241
### Test Mode:
203242
Run with `--test` flag to try without a connected device.
243+
244+
### Alternative Installation:
245+
If you prefer to avoid the executable, run from Python source:
246+
```bash
247+
git clone https://github.com/PixelCode01/UIBloatwareRegistry.git
248+
cd UIBloatwareRegistry
249+
python main.py
250+
```
204251
draft: false
205252
prerelease: false
206253
files: release/*

‎README.md‎

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ Your phone comes with tons of apps you never asked for. This tool helps you get
2020
- Motorola (My UX)
2121
- Nothing (Nothing OS)
2222

23-
## Quick Download (Recommended)
23+
## Quick Download
2424

2525
**Download standalone executable** - No Python installation required!
2626

@@ -31,6 +31,8 @@ Your phone comes with tons of apps you never asked for. This tool helps you get
3131
- **Mac**: `android-bloatware-remover-macos`
3232
3. Run the executable directly!
3333

34+
**Note**: Windows Defender may show a false positive. See [SECURITY.md](SECURITY.md) for details.
35+
3436
## Manual Setup (Advanced)
3537

3638
1. **Install ADB**
@@ -111,8 +113,12 @@ Proceed? (yes): yes
111113

112114
Found a bug? Want to add support for your phone brand? Check out [CONTRIBUTING.md](CONTRIBUTING.md).
113115

114-
## Warning
116+
## Important Notes
117+
118+
### Windows Defender False Positive
119+
Windows Defender may flag the executable as a virus. This is a **false positive** common with PyInstaller executables. The tool is completely safe - all source code is open and auditable. See [SECURITY.md](SECURITY.md) for details and solutions.
115120

121+
### Safety Warning
116122
This tool modifies your phone's software. We're not responsible if something breaks. Use common sense and make backups.
117123

118124
## License

‎SECURITY.md‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
# Security Information
2+
3+
## Windows Defender False Positives
4+
5+
### Why does Windows Defender flag this as a virus?
6+
7+
This is a **false positive** that commonly occurs with PyInstaller executables. Here's why:
8+
9+
1. **PyInstaller behavior**: PyInstaller bundles Python and all dependencies into a single executable, which can trigger heuristic detection
10+
2. **Unsigned executable**: The executable isn't code-signed with a certificate, making Windows more suspicious
11+
3. **ADB interaction**: The tool interacts with ADB (Android Debug Bridge), which antivirus software may flag as suspicious
12+
4. **New executable**: Windows Defender is more likely to flag new, uncommon executables
13+
14+
### Is it actually safe?
15+
16+
**Yes, it's completely safe.** Here's how you can verify:
17+
18+
1. **Source code is open**: All source code is available in this repository for inspection
19+
2. **Build process is transparent**: GitHub Actions builds are public and auditable
20+
3. **No network activity**: The tool only communicates with your connected Android device via ADB
21+
4. **No system modifications**: Only removes apps you explicitly select
22+
23+
### How to use safely
24+
25+
#### Option 1: Add Windows Defender Exception
26+
1. Open Windows Security
27+
2. Go to "Virus & threat protection"
28+
3. Click "Manage settings" under "Virus & threat protection settings"
29+
4. Click "Add or remove exclusions"
30+
5. Add the downloaded executable file
31+
32+
#### Option 2: Use Python Source (Recommended for paranoid users)
33+
Instead of the executable, run from source:
34+
```bash
35+
git clone https://github.com/PixelCode01/UIBloatwareRegistry.git
36+
cd UIBloatwareRegistry
37+
python main.py
38+
```
39+
40+
#### Option 3: Build Your Own Executable
41+
```bash
42+
git clone https://github.com/PixelCode01/UIBloatwareRegistry.git
43+
cd UIBloatwareRegistry
44+
pip install pyinstaller
45+
python build_spec.py
46+
pyinstaller android-bloatware-remover.spec
47+
```
48+
49+
### Verification Steps
50+
51+
1. **Check file hash**: Compare with hashes provided in releases
52+
2. **Scan with multiple engines**: Use VirusTotal.com to scan with 60+ antivirus engines
53+
3. **Review source code**: Inspect the code before running
54+
4. **Test in VM**: Run in a virtual machine first if concerned
55+
56+
## Reporting Security Issues
57+
58+
If you find a legitimate security issue, please:
59+
60+
1. **Do NOT** open a public issue
61+
2. Email security concerns to the repository owner
62+
3. Provide detailed information about the vulnerability
63+
4. Allow time for the issue to be addressed before public disclosure
64+
65+
## Code Signing
66+
67+
We are working on implementing code signing to reduce false positives. This requires:
68+
- Purchasing a code signing certificate
69+
- Setting up automated signing in the build process
70+
- Establishing trust with certificate authorities
71+
72+
## Best Practices for Users
73+
74+
1. **Always download from official releases**: Only download from GitHub releases page
75+
2. **Verify checksums**: Compare file hashes when provided
76+
3. **Use test mode first**: Run with `--test` flag to verify functionality
77+
4. **Keep backups**: Always backup your device before removing apps
78+
5. **Review what you're removing**: Understand each package before removal
79+
80+
## Technical Details
81+
82+
### What the tool does:
83+
- Connects to Android devices via ADB
84+
- Lists installed packages
85+
- Removes selected packages using `adb shell pm uninstall`
86+
- Creates backup files locally
87+
- Logs operations for troubleshooting
88+
89+
### What the tool does NOT do:
90+
- Access the internet (except for ADB communication)
91+
- Modify system files on your computer
92+
- Install anything on your computer
93+
- Send data to external servers
94+
- Access personal files or data
95+
96+
### ADB Commands Used:
97+
```bash
98+
adb devices # List connected devices
99+
adb shell getprop ro.product.brand # Get device brand
100+
adb shell pm list packages # List installed packages
101+
adb shell pm uninstall --user 0 <pkg> # Remove package
102+
```
103+
104+
All commands are standard ADB operations used by Android developers worldwide.

‎generate_hashes.py‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
#!/usr/bin/env python3
2+
"""
3+
Generate SHA256 hashes for release files
4+
"""
5+
6+
import hashlib
7+
import os
8+
import sys
9+
10+
def calculate_sha256(file_path):
11+
"""Calculate SHA256 hash of a file"""
12+
sha256_hash = hashlib.sha256()
13+
try:
14+
with open(file_path, "rb") as f:
15+
for chunk in iter(lambda: f.read(4096), b""):
16+
sha256_hash.update(chunk)
17+
return sha256_hash.hexdigest()
18+
except FileNotFoundError:
19+
return None
20+
21+
def main():
22+
"""Generate hashes for release files"""
23+
files_to_hash = [
24+
"dist/android-bloatware-remover.exe",
25+
"dist/android-bloatware-remover"
26+
]
27+
28+
print("# File Verification Hashes")
29+
print()
30+
print("Use these SHA256 hashes to verify file integrity:")
31+
print()
32+
33+
for file_path in files_to_hash:
34+
if os.path.exists(file_path):
35+
hash_value = calculate_sha256(file_path)
36+
file_size = os.path.getsize(file_path)
37+
print(f"**{os.path.basename(file_path)}**")
38+
print(f"- SHA256: `{hash_value}`")
39+
print(f"- Size: {file_size:,} bytes")
40+
print()
41+
else:
42+
print(f"File not found: {file_path}")
43+
44+
print("## How to verify:")
45+
print()
46+
print("**Windows (PowerShell):**")
47+
print("```powershell")
48+
print("Get-FileHash -Algorithm SHA256 android-bloatware-remover-windows.exe")
49+
print("```")
50+
print()
51+
print("**Linux/Mac:**")
52+
print("```bash")
53+
print("sha256sum android-bloatware-remover-linux")
54+
print("# or")
55+
print("shasum -a 256 android-bloatware-remover-macos")
56+
print("```")
57+
58+
if __name__ == "__main__":
59+
main()

0 commit comments

Comments
 (0)