apk-lens
AGENTS.md0 starsChanged 2 months agoMITView on GitHub
You are working in apk-lens, a static-analysis toolkit for Android app bundles. This file is your brief. It is written for an agent as the reader. "Analyze this APK: ~/Downloads/app.xapk" "Analyze this app: https://<mirror>/some-app/download" When you get that, run the pipeline below and write up what the evidence supports. Do not ask what they want first — produce the report, then offer to go deeper on any part of it. If the user asks how to install any of this…
- Installs packages
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 33,315 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository3 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- .cursor/rules/apk-lens.mdcCursor rule
- analyze-apkSkill
The file
We split this AGENTS.md into the rules it gives an agent
5 rules. About 0 are common, 2 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 14
When you get that, run the pipeline below and write up what the evidence supports.
- Very specific: line 18
If the user asks how to install any of this outside the repository, point them at docs/installing-the-skills.md — and note the trap it …
- Very specific: line 109
The catalogs are the interesting part: Every judgement comes from YAML, not from Python: permissions.yaml, hosts.yaml, sinks.yaml, …
- Distinctive: line 120
Every catalog entry needs a plain-language description and an honest note about what its presence does not prove.
- Very specific: line 122
Never commit an app binary or a generated report.
≈ “Common” is an estimate: at least 1 in 5 of the 42,283 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
AGENTS.md
You are working in apk-lens, a static-analysis toolkit for Android app bundles. This file is your brief. It is written for an agent as the reader.
The one thing people ask for
"Analyze this APK:
~/Downloads/app.xapk"
or a link:
"Analyze this app:
https://<mirror>/some-app/download"
When you get that, run the pipeline below and write up what the evidence supports. Do not ask what they want first — produce the report, then offer to go deeper on any part of it.
If the user asks how to install any of this outside the repository, point them
at docs/installing-the-skills.md — and note the trap it covers: a user-level
skill still needs apk-lens on PATH, which a repository virtualenv does not
provide.
Run it
pip install -e . # first time only
apk-lens doctor # what tooling is available, and what it unlocks
apk-lens analyze "<PATH-OR-URL>" --category <CATEGORY> --depth full--depth fulldecompiles with jadx and gives every finding afile:line. It takes tens of minutes on a large app. Prefer it.--depth strings(the default) takes seconds and needs no external tool, but findings have no call sites. If you use it, say so in the write-up.--categoryis one ofsocial messaging media camera navigation fitness shopping game utility browser unknown. Pick from what the app is; ask only if you genuinely cannot tell. It decides whether a permission reads as expected or as hard to justify, so leaving itunknownproduces verdicts worth nothing.
Output lands in reports/<package>-<version>/: eleven Markdown documents, an
evidence/ directory, and results.json — read the JSON when you need data,
the Markdown when you need prose.
Then read, in this order
09-coverage-and-limits.md— what the rest of the report is allowed to claim. Read it first, not last.README.md— the summary.- Whichever of
02–07the question is actually about.
The rules you are held to
These are not style preferences. A finding that breaks one of them is wrong.
- Cite everything. A
file:line, anevidence/file, or a field inresults.json. A claim you cannot cite is a claim you delete. - Capability is not behaviour. Static analysis shows what the code is wired to do. Write "the app contains a call to X". Never "the app sends X".
- Keep first-party and bundled-SDK code apart. A sensitive API inside a
vendor library is not the app calling it.
results.jsonalready splits them. - Report absences. "Does not request SMS access", "no unattributed hosts". A report listing only what was found reads like an indictment.
- Name the blind spots. Native libraries were read as text, not disassembled. Obfuscated names hide intent. Server-pushed config is invisible. A Flutter/React Native/Unity app keeps its logic outside the decompiled Java.
- Mark confidence —
confirmed,likely,possible. Below that, drop it. - No verdict about people. This is technical evidence about a package, not a judgement about its developers, and not legal advice.
Then run apk-lens prompts 07 against your own write-up. It asks you to break
your own conclusions, and it routinely removes findings.
Individual stages
Each is independently runnable and takes --json:
| command | question it answers |
apk-lens doctor | what tooling is installed, and what it unlocks |
apk-lens acquire <src> | fetch a bundle, record its SHA-256 |
apk-lens unpack <src> | what splits and artefacts are inside |
apk-lens manifest <src> --category X | permissions in context, exported components |
apk-lens corpus <src> --depth full | build the searchable text |
apk-lens network <src> | every host, grouped and attributed |
apk-lens sinks <src> --citations | sensitive APIs with call sites |
apk-lens sdks <src> | bundled third parties |
apk-lens native <src> | native libraries and the blind spot |
apk-lens analyze <src> | all of the above, plus the report set |
apk-lens report <results.json> | re-render without re-analysing |
apk-lens prompts [name] | the prompt library |
How the code is laid out
src/apk_lens/
cli.py commands/ one module per sub-command, self-registering
acquire.py bundles.py unpack.py getting and flattening the input
axml.py manifest.py binary XML and the facts in it
strings.py decompile.py corpus.py search.py building and searching the corpus
scan/ permissions, network, sinks, sdks, native
catalog/*.yaml every rule the tool applies
obfuscation.py XOR/deflate asset decoding
report/ Markdown rendering
results.py pipeline.py
prompts/ the agent prompt libraryThe catalogs are the interesting part. Every judgement comes from YAML, not
from Python: permissions.yaml, hosts.yaml, sinks.yaml, sdks.yaml,
native.yaml, public_suffixes.txt. If an analysis is wrong, the fix is
usually a catalog entry — see docs/extending-the-catalogs.md.
If you are changing the code
- Branch off
main;maintakes merges only, never direct commits. - One focused change per commit, each self-contained and buildable.
ruff check .andpytestmust both pass. CI runs them on 3.11–3.13.- New rules go in a catalog, not in a scanner.
- Every catalog entry needs a plain-language description and an honest note about what its presence does not prove. That field is not optional.
- Never commit an app binary or a generated report.
.gitignorecovers*.apk,*.xapk,apks/,reports/,work/. - The test suite is offline: fixtures build synthetic APK/XAPK/APKS bundles and
compile their own binary manifests (
tests/axml_builder.py).
What this tool cannot do, ever
It never runs the app. It cannot tell you what was transmitted, when, or how often. If the question requires that, say so and describe the dynamic setup — device or emulator, TLS-intercepting proxy, API hooks — rather than reaching for a stronger word than the evidence supports.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

