From 1ac66a99e50cf86242df2afb74d3404c20ac12a1 Mon Sep 17 00:00:00 2001 From: Philippe Ombredanne Date: Sat, 28 Sep 2024 14:02:04 +0200 Subject: [PATCH 1/2] Improve README with detailed example Signed-off-by: Philippe Ombredanne --- README.rst | 128 ++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 122 insertions(+), 6 deletions(-) diff --git a/README.rst b/README.rst index 9644dee..2f06977 100644 --- a/README.rst +++ b/README.rst @@ -1,12 +1,128 @@ -Android Inspector ================= -A collection of ScanCode.io pipelines dedicated to Android APK analysis. +android-inspector +================= + +android-inspector is a set of utilities to inspect binary Android application APK as well as Android +firmwares. This is also a ScanCode.io pipeline plugin. + +The available features are: + +- Extract and map the files found in a binary Android application to the assumed corresponding + source code. + +Other information: + +- License: Apache-2.0 +- Copyright (c) nexB Inc., AboutCode.org and others. +- Homepage: https://github.com/aboutcode-org/android-inspector/ + Requirements ------------ -- Java 11+ -- jadx 1.5.0 `https://github.com/skylot/jadx` +- ScanCode.io https://github.com/nexB/scancode.io +- Ensure Java 11+ is in your path (using an OpenJDK installation) +- Install jadx 1.5.0 https://github.com/skylot/jadx (You will need to add jadx to your path or + moved its ``bin`` and ``lib`` directories to your ``/usr`` directory. + +See also the next section for detailed instructions. + + +Local installation and usage test +------------------------------------ + +To install: +~~~~~~~~~~~~ + +- Clone android-inspector locally side-by-side: ``git clone https://github.com/aboutcode-org/android-inspector`` +- Clone ScanCode.io locally side-by-side: ``git clone https://github.com/aboutcode-org/scancode.io`` +- Change to the scancode.io directory and run ``make dev`` then ``source bin/activate`` + + - Follow the full instructions at https://scancodeio.readthedocs.io/en/latest/installation.html#local-development-installation + +- Install jadx minimally + + - Download https://github.com/skylot/jadx/releases/download/v1.5.0/jadx-1.5.0.zip in your + scancode.io directory + - Extract with ``unzip -qd jadx-1.5.0 jadx-1.5.0.zip`` + - Add the extracted directory jadx-1.5.0/bin and jadx-1.5.0/lib to your path with + ``export PATH=$PATH:`pwd`/jadx-1.5.0/bin/jadx:`pwd`/jadx-1.5.0/lib`` + +- Run ``pip install --editable ../android-inspector`` +- Run ScanCode.io with ``./manage.py runserver --insecure`` and open the URL in your browser. + There is a new "android_d2d" pipeline available when creating a new project. + + +To use with example Android APKs and sources: +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Create a new project and name it "sample-apk-analysis" +- In the input section, add ``Download URLs`` for the source and binary of a public APK: + +You can use this pair of source (aka. "from") and binaries (aka. "to"): + + - https://github.com/ochadenas/cpudefense/archive/refs/tags/v1.42.zip#from + - https://f-droid.org/repo/de.chadenas.cpudefense_42.apk#to + +Or you can use alternatively this other example pair: + +- https://github.com/Acclorite/book-story/archive/refs/tags/v1.3.0.tar.gz#from +- https://github.com/Acclorite/book-story/releases/download/v1.3.0/book-story.apk#to + +Then: + +- Select "android_d2d" in the pipeline dropdown and click "create". +- Wait for the pipeline to complete, and check the created Relations as well as the missing "To" + source files resulting from mapping the binaries back to sources. + +At this stage we typically report missing many source files because these are not present in the +source code reposirories. In particular: + +- PurlDB matching would be enabled in a full ScanCode.io installation and could help match + the Android toolchain and standard library if indexed. +- There is a significant number of standard library Java files that are part of the Android + toolchain. This will be resolved with this issue https://github.com/aboutcode-org/android-inspector/issues/3 + + +Development +---------------- + +- Install requirements and dependencies using ``make dev`` +- Then ``source venv/bin/activate`` + +Testing: + +- To run tests: ``pytest -vvs`` + + +Funding, support and sponsoring +----------------------------------- + +This project is funded, supported and sponsored through: + +- Generous support and contributions from users like you! + +- NGI Zero Core `https://nlnet.nl/core`, a fund established by NLnet with + financial support from the European Commission's Next Generation Internet `https://ngi.eu` program. + Learn more at the NLnet project page `https://nlnet.nl/Back2source-next` + + |nlnet| and |ngizerocore| + +- Support from nexB Inc. |nexb| + + + +.. |nlnet| image:: https://nlnet.nl/logo/banner.png + :target: https://nlnet.nl + :height: 50 + :alt: NLnet foundation logo + +.. |ngizerocore| image:: https://nlnet.nl/image/logos/NGI0_tag.svg + :target: https://nlnet.nl/core + :height: 50 + :alt: NGI Zero Logo -Ensure that jadx is available in your path by moving the `bin` and `lib` -directories to the `/usr` directory. +.. |nexb| image:: https://nexb.com/wp-content/uploads/2022/04/nexB.svg + :target: https://nexb.com + :height: 30 + :alt: nexB logo From 511aa4fdffbab92a8915d0e0496613747df6c886 Mon Sep 17 00:00:00 2001 From: Philippe Ombredanne Date: Sat, 28 Sep 2024 14:02:26 +0200 Subject: [PATCH 2/2] Use correct package path for pipeline Signed-off-by: Philippe Ombredanne --- setup.cfg | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/setup.cfg b/setup.cfg index 12c5559..598b8a1 100644 --- a/setup.cfg +++ b/setup.cfg @@ -8,7 +8,7 @@ long_description = file:README.rst long_description_content_type = text/x-rst url = https://github.com/aboutcode-org/android-inspector -author = nexB. Inc. and others +author = nexB. Inc., AboutCode and others author_email = info@aboutcode.org classifiers = @@ -73,4 +73,4 @@ docs = [options.entry_points] scancodeio_pipelines = - android_d2d = scanpipe.pipelines.android_d2d:AndroidAPKDeployToDevelop + android_d2d = android_inspector.pipelines.android_d2d:AndroidAPKDeployToDevelop