Skip to content

Commit 0aeebdd

Browse files
author
root
committed
feat: production-ready infrastructure
- Add GitHub Actions CI with shellcheck - Add CONTRIBUTING.md, SECURITY.md, CHANGELOG.md - Add issue templates and PR template - Add .editorconfig - Enhance README with badges, FAQ, troubleshooting
1 parent f917873 commit 0aeebdd

9 files changed

Lines changed: 342 additions & 0 deletions

File tree

‎.editorconfig‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
root = true
2+
3+
[*]
4+
charset = utf-8
5+
end_of_line = lf
6+
insert_final_newline = true
7+
trim_trailing_whitespace = true
8+
indent_style = space
9+
indent_size = 4
10+
11+
[*.md]
12+
trim_trailing_whitespace = false
13+
14+
[*.sh]
15+
indent_style = space
16+
indent_size = 4
17+
18+
[Makefile]
19+
indent_style = tab

‎.github/ISSUE_TEMPLATE/bug_report.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
---
2+
name: Bug report
3+
about: Create a report to help us improve pocket-kali
4+
title: ""
5+
labels: bug
6+
assignees: ""
7+
---
8+
9+
**Describe the bug**
10+
A clear and concise description of what the bug is.
11+
12+
**To Reproduce**
13+
Steps to reproduce the behavior:
14+
15+
1. Run `curl -sL ... | bash`
16+
2. See error at step X
17+
3. ...
18+
19+
**Expected behavior**
20+
What you expected to happen.
21+
22+
**Logs**
23+
Paste the contents of `~/pocket-kali.log`:
24+
25+
```
26+
...
27+
```
28+
29+
**Environment (please complete):**
30+
31+
- Android version: [e.g. 12]
32+
- Device architecture: [e.g. aarch64, `uname -m`]
33+
- Termux version: [e.g. from `termux-info`]
34+
- Termux source: [F-Droid / GitHub / Google Play]
35+
- RAM: [e.g. 4 GB]
36+
- Free storage: [e.g. 8 GB]
37+
38+
**Screenshots**
39+
If applicable, add screenshots to help explain your problem.
40+
41+
**Additional context**
42+
Anything else relevant.

‎.github/ISSUE_TEMPLATE/feature_request.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
---
2+
name: Feature request
3+
about: Suggest an idea for pocket-kali
4+
title: ""
5+
labels: enhancement
6+
assignees: ""
7+
---
8+
9+
**Is your feature request related to a problem? Please describe.**
10+
A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
11+
12+
**Describe the solution you'd like**
13+
A clear and concise description of what you want to happen.
14+
15+
**Describe alternatives you've considered**
16+
A clear and concise description of any alternative solutions or features you've considered.
17+
18+
**Additional context**
19+
Add any other context or screenshots about the feature request here.

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
## Description
2+
3+
Please include a summary of the change and which issue is fixed.
4+
5+
Fixes #(issue)
6+
7+
## Type of change
8+
9+
- [ ] Bug fix (non-breaking change which fixes an issue)
10+
- [ ] New feature (non-breaking change which adds functionality)
11+
- [ ] Breaking change (fix or feature that would break existing functionality)
12+
- [ ] Documentation update
13+
14+
## How Has This Been Tested?
15+
16+
- [ ] Tested locally with `shellcheck install.sh`
17+
- [ ] Tested inside Termux (or proot environment)
18+
- [ ] Install ran successfully end-to-end
19+
20+
## Checklist:
21+
22+
- [ ] My code follows the style guidelines of this project
23+
- [ ] I have performed a self-review of my own changes
24+
- [ ] I have commented my code, particularly in hard-to-understand areas (if applicable)
25+
- [ ] My changes generate no new shellcheck warnings

‎.github/workflows/ci.yml‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches: [main]
6+
pull_request:
7+
branches: [main]
8+
9+
jobs:
10+
shellcheck:
11+
runs-on: ubuntu-latest
12+
steps:
13+
- uses: actions/checkout@v4
14+
- name: Run ShellCheck
15+
uses: ludeeus/action-shellcheck@master
16+
with:
17+
scandir: "."
18+
severity: warning

‎CHANGELOG.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# Changelog
2+
3+
All notable changes to this project will be documented in this file.
4+
5+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7+
8+
## [1.0.0] - 2024-01-15
9+
10+
### Added
11+
12+
- Initial release of pocket-kali
13+
- One-command installer (`curl ... | bash`)
14+
- Automated system compatibility check (architecture, storage)
15+
- Termux dependency installation (`proot-distro`, `termux-x11-nightly`, `pulseaudio`, `axel`)
16+
- Kali Nethunter rootfs download with 4 fallback extraction methods
17+
- XFCE4 desktop with Kali-dark theming
18+
- Performance optimizations (compositing disabled, single workspace, motd disabled)
19+
- PulseAudio TCP forwarding for audio in X11 sessions
20+
- `kali` and `kali-gui` launcher commands
21+
- Idempotent install — safe to re-run (state tracking via `~/.pocket-kali/`)
22+
- Anonymous install counter

‎CONTRIBUTING.md‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
# Contributing to pocket-kali
2+
3+
First off, thanks for taking the time to contribute!
4+
5+
## Code of Conduct
6+
7+
This project adheres to the [Contributor Covenant](https://www.contributor-covenant.org/). By participating, you are expected to uphold this code.
8+
9+
## How Can I Contribute?
10+
11+
### Reporting Bugs
12+
13+
Open a [bug report](https://github.com/highoncomputers/pocket-kali/issues/new?template=bug_report.md) and include:
14+
15+
- Your Android version and architecture (`uname -m`)
16+
- Termux version (`pkg show termux` or `termux-info`)
17+
- The contents of `~/pocket-kali.log` if the install failed
18+
- Steps to reproduce
19+
20+
### Suggesting Features
21+
22+
Open a [feature request](https://github.com/highoncomputers/pocket-kali/issues/new?template=feature_request.md).
23+
24+
### Pull Requests
25+
26+
1. Fork the repo and create your branch from `main`.
27+
2. If you've changed shell logic, run `shellcheck install.sh`.
28+
3. Ensure your changes are tested inside Termux (or a proot environment).
29+
4. Open a PR against `main` using the [PR template](https://github.com/highoncomputers/pocket-kali/blob/main/.github/PULL_REQUEST_TEMPLATE.md).
30+
31+
## Style Guide
32+
33+
- **Shell**: Target `bash` (specifically the Termux bash at `/data/data/com.termux/files/usr/bin/bash`).
34+
- **Quoting**: Always double-quote variable expansions (`"$var"`) unless you explicitly need word splitting.
35+
- **Error handling**: Use `set -euo pipefail` in standalone scripts; use explicit error checks in the installer.
36+
- **Functions**: Use `snake_case` for function names.
37+
- **Colors**: Use the `info()`, `ok()`, `warn()`, `error_()` helpers defined in `install.sh`.
38+
- **Logging**: Write structured log entries with `log "LEVEL" "message"`.
39+
40+
## Testing
41+
42+
- Run `shellcheck install.sh` on any changes to the installer.
43+
- If you add or modify Termux package installation, verify the package name is correct for the `stable` and `x11-repo` repos.
44+
- For rootfs changes, test with a fresh install (back up your existing Kali container first).
45+
46+
## Project Structure
47+
48+
```
49+
pocket-kali/
50+
├── install.sh # One-shot installer
51+
├── LICENSE # GPL-3.0
52+
├── README.md # Project documentation
53+
├── CHANGELOG.md # Release history
54+
├── CONTRIBUTING.md # This file
55+
├── SECURITY.md # Security policy
56+
├── .editorconfig # Editor settings
57+
└── .github/
58+
├── workflows/
59+
│ └── ci.yml # GitHub Actions CI
60+
├── ISSUE_TEMPLATE/
61+
│ ├── bug_report.md
62+
│ └── feature_request.md
63+
└── PULL_REQUEST_TEMPLATE.md
64+
```
65+
66+
## License
67+
68+
By contributing, you agree that your contributions will be licensed under the GPL-3.0 license.

‎README.md‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,19 @@
11
# pocket-kali
22

3+
<p align="center">
4+
<a href="https://github.com/highoncomputers/pocket-kali/releases"><img alt="GitHub release" src="https://img.shields.io/github/v/release/highoncomputers/pocket-kali?style=flat-square"></a>
5+
<a href="LICENSE"><img alt="License: GPL-3.0" src="https://img.shields.io/badge/license-GPL--3.0-blue.svg?style=flat-square"></a>
6+
<a href="https://github.com/highoncomputers/pocket-kali/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/highoncomputers/pocket-kali/ci.yml?branch=main&style=flat-square&label=CI"></a>
7+
<a href="https://github.com/highoncomputers/pocket-kali"><img alt="Platform" src="https://img.shields.io/badge/platform-Android%20%7C%20Termux-brightgreen?style=flat-square"></a>
8+
<a href="https://github.com/highoncomputers/pocket-kali/stargazers"><img alt="Stars" src="https://img.shields.io/github/stars/highoncomputers/pocket-kali?style=flat-square"></a>
9+
</p>
10+
311
**One-command Kali Linux + XFCE4 desktop for Termux — Zero configuration, fully automated.**
412

13+
## Screenshot
14+
15+
> *Screenshot coming soon — submit one via PR!*
16+
517
## Quick Start
618

719
Open Termux and run:
@@ -86,6 +98,87 @@ Launches a full XFCE4 desktop via Termux X11 with the Kali dragon wallpaper.
8698
- **Single workspace** — reduces XFCE4 memory overhead
8799
- **Battery optimization**: Go to Settings > Apps > Termux > Battery > Unrestricted to prevent Android from killing the background session
88100

101+
## FAQ
102+
103+
**Q: Do I need root (su) to run this?**
104+
105+
A: No. pocket-kali runs entirely inside Termux's sandboxed environment.
106+
107+
**Q: Why does the installer use F-Droid Termux and not Google Play?**
108+
109+
A: The Google Play version of Termux is outdated and lacks features like `termux-x11`. Always use F-Droid.
110+
111+
**Q: Can I install additional tools after the setup?**
112+
113+
A: Yes — run `kali` and then `apt-get install <package>` as usual.
114+
115+
**Q: What if the download fails?**
116+
117+
A: The installer retries up to 3 times with `axel`. If it still fails, check your internet connection and try again.
118+
119+
**Q: How do I uninstall pocket-kali?**
120+
121+
A: Remove the Kali proot container with `proot-distro remove kali` and delete `~/.pocket-kali/`.
122+
123+
**Q: Does this work on 32-bit (armv7l) devices?**
124+
125+
A: The Kali Nethunter rootfs is ARM64 only. 32-bit devices are not supported.
126+
127+
**Q: Will this work on non-Android Linux (e.g., ChromeOS Linux container)?**
128+
129+
A: No — the installer checks for Termux's `/data/data/com.termux` directory and will exit if not found.
130+
131+
## Troubleshooting
132+
133+
### "kali: command not found"
134+
135+
Run `source ~/.bashrc` or restart Termux. If it persists, check `~/bin/` was created:
136+
137+
```bash
138+
ls -la ~/bin/kali
139+
```
140+
141+
### GUI doesn't start / X11 blank screen
142+
143+
1. Make sure **Termux-X11 APK** is installed — download from the [releases page](https://github.com/termux/termux-x11/releases).
144+
2. Set **Termux battery to Unrestricted** — `Settings > Apps > Termux > Battery > Unrestricted`.
145+
3. Run `killall termux-x11 2>/dev/null; killall pulseaudio 2>/dev/null` then try `kali-gui` again.
146+
4. If still broken, check the log: `cat ~/pocket-kali.log | tail -50`.
147+
148+
### Installation stuck at "Installing Kali Linux Rootfs"
149+
150+
The rootfs tarball is ~300 MB. On slow connections this can take 10+ minutes. Check `~/pocket-kali.log` for download progress. If it truly hangs, cancel (Ctrl+C) and re-run — the installer is idempotent.
151+
152+
### Audio not working
153+
154+
Restart PulseAudio:
155+
156+
```bash
157+
pulseaudio --kill 2>/dev/null; pulseaudio --start
158+
```
159+
160+
Then do `kali-gui` again. Inside the Kali session, verify PulseAudio is connecting:
161+
162+
```bash
163+
pactl info
164+
```
165+
166+
### Out of space
167+
168+
Kali rootfs + XFCE4 takes ~1.5 GB after installation. Run `kali` then `apt-get clean` to clear package cache.
169+
170+
## Contributing
171+
172+
See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on reporting bugs, suggesting features, and submitting pull requests.
173+
174+
## Security
175+
176+
See [SECURITY.md](SECURITY.md) for our security policy and vulnerability reporting process.
177+
178+
## Changelog
179+
180+
See [CHANGELOG.md](CHANGELOG.md) for release history.
181+
89182
## Credits
90183

91184
Built on the [Kali Nethunter rootfs](https://www.kali.org/docs/nethunter/) — the official Kali Linux distribution for mobile devices.

‎SECURITY.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# Security Policy
2+
3+
## Supported Versions
4+
5+
| Version | Supported |
6+
|---------|--------------------|
7+
| 1.0.x | :white_check_mark: |
8+
9+
## Reporting a Vulnerability
10+
11+
If you discover a security vulnerability in pocket-kali, please **do not** open a public issue.
12+
13+
Instead, email the maintainer directly or open a [draft security advisory](https://github.com/highoncomputers/pocket-kali/security/advisories/new).
14+
15+
We will acknowledge receipt within **48 hours** and provide an estimated timeline for a fix.
16+
17+
## Scope
18+
19+
pocket-kali downloads and installs third-party software (Termux packages, Kali Nethunter rootfs). We are not responsible for vulnerabilities in those upstream projects. Please report them to the respective maintainers:
20+
21+
- **Termux**: https://github.com/termux/termux-packages/issues
22+
- **Kali Linux**: https://bugs.kali.org/
23+
- **XFCE4**: https://gitlab.xfce.org/
24+
25+
## Self-Assessment
26+
27+
pocket-kali runs as a non-root process inside Termux's sandboxed environment. The installer:
28+
29+
- Does **not** require device root (no `su`).
30+
- Does **not** collect or transmit personal data (aside from an anonymous install counter).
31+
- Does **not** open network ports on the host (SSH runs inside the proot container only).
32+
33+
## Recommendations
34+
35+
- Always install Termux from **F-Droid** (not Google Play) to get the latest security patches.
36+
- Review `install.sh` before running it — the project values transparency.

0 commit comments

Comments
 (0)