diff --git a/docs/cli-parameters.mdx b/docs/cli-parameters.mdx index b0501e029d..0db149cc27 100644 --- a/docs/cli-parameters.mdx +++ b/docs/cli-parameters.mdx @@ -17,7 +17,7 @@ _Options used for utility commands (`apktool {options}`)_ -version, --version ``` -- Outputs current version. (Ex: 1.5.2 +- Outputs current version. (Ex: 1.5.2) ### Decoding Options @@ -84,6 +84,15 @@ _Options used for decoding commands (`apktool d file.apk {options}`)_ - This will prevent the decompile of resources. This keeps the `resources.arsc` +``` +-resm,--resource-mode +``` + +- The mode to use when resolving resources. Presently supported options are: + - `remove` (default) - Remove resources that cannot be resolved. + - `dummy` - Add a dummy resource for resources that cannot be resolved. + - `keep` - Keep unresolved resources using `APKTOOL_MISSING_{resId}` nomenclature. + ``` -s, --no-src ``` diff --git a/docs/in-depth/resource-modes.mdx b/docs/in-depth/resource-modes.mdx new file mode 100644 index 0000000000..701892ef7e --- /dev/null +++ b/docs/in-depth/resource-modes.mdx @@ -0,0 +1,132 @@ +--- +title: Resource Modes +sidebar_position: 3 +--- + +Introduced in Apktool v2.9.0 added configuration for how Apktool decides to handle unresolved resources during disassembly. + +## Background + +Given an application you could leverage aapt (`aapt d resources app.apk`) to get a view of the resources in play. + +```text +➜ aapt d resources bugged.apk +Package Groups (1) +Package Group 0 id=0x7f packageCount=1 name=com.ibotpeaches.arsctest + Package 0 id=0x7f name=com.ibotpeaches.arsctest + type 0 configCount=1 entryCount=10 + spec resource 0x7f010000 com.ibotpeaches.arsctest:color/black: flags=0x00000000 + spec resource 0x7f010001 com.ibotpeaches.arsctest:color/purple_200: flags=0x00000000 + spec resource 0x7f010002 com.ibotpeaches.arsctest:color/purple_500: flags=0x00000000 + spec resource 0x7f010003 com.ibotpeaches.arsctest:color/purple_700: flags=0x00000000 + spec resource 0x7f010004 com.ibotpeaches.arsctest:color/teal_200: flags=0x00000000 + spec resource 0x7f010005 com.ibotpeaches.arsctest:color/teal_700: flags=0x00000000 + spec resource 0x7f010006 com.ibotpeaches.arsctest:color/white: flags=0x00000000 + INVALID TYPE CONFIG FOR RESOURCE 0x7f010007 + INVALID TYPE CONFIG FOR RESOURCE 0x7f010008 + spec resource 0x7f010009 com.ibotpeaches.arsctest:color/bugged: flags=0x00000000 +``` + +In this example you can see the following two resources had issues being resolved: + +- `0x7f010007` +- `0x7f010008` + +The problem being though that the message exposed to end user is just a wrapper of the underlying issue, which could be one of the following: + +- No package found for resource. +- No type found for resource. +- Invalid identifier for resource name. +- Invalid UTF-8 index during unpack of strings. +- Invalid UTF-16 index during unpack of strings. +- Entry not found for resource. + +So basically it is difficult to understand the exact reason this occurs. + +## History + +Apktool prior to being able to keep resource ids static - would intentionally make dummy resources for any of these issues. + +These would be resources like: + +```xml + + +``` + +So when the resource table was built - the ids would not shift as dummy resources filled all locations in which resources did not disassemble properly. + +Over time, this became unneeded because resource ids were kept static at the cost of turning them public. Something that continues to bite us in the increasing +security of Android to this day. + +Additionally, this became a bit of a problem because Apktool would unintentionally fingerprint applications with dummy resources. In 2019 this was noticed +when a large company used Apktool in order to rename their package and republish to the store. This post can be found [here](https://connortumbleson.com/2019/06/02/apktool-in-the-wild/). + +So unintentionally dummy resources just broke during the support of sparse resources and people didn't really notice. This was a good thing, but it led to +some odd issues that were previously handled. + +Given an example like follows: + +```xml + + + +``` + +This is how Apktool disassembled an unknown application during the v2.8.x release cycle. This was improper as an unresolved resource name cannot be `@null`. + +However, would replacing this with a dummy resource be better? + +```xml + + + +``` + +You could argue it was better, but chances are if you are disassembling a resource with no references to this attribute - it would seem odd to invent a dummy resource to fulfill it. + +So it seemed another alternative was to just remove unresolved resources. + +```xml + +``` + +The challenge here that every single use-case might prefer a different option. + +## Modes + +During disassembly run `-resm ` to set the mode for how Apktool should handle unresolved resources. + +### Remove (default) + +- `remove` | `delete` + +Apktool will remove any unresolved resource. This is the default behavior. + +```xml + +``` + +### Dummy + +- `dummy` | `dummies` + +Apktool will populate unresolved resources with dummy values. + +```xml + + + +``` + +### Keep + +- `keep` | `preserve` + +Apktool will leave resources, but properly make up valid resource names if the name was stripped. + +```xml + + + +``` diff --git a/docs/unreleased.mdx b/docs/unreleased.mdx index 47fb146c36..4f599f661b 100644 --- a/docs/unreleased.mdx +++ b/docs/unreleased.mdx @@ -9,6 +9,7 @@ The changelog of the upcoming release, subject to change prior to finalization. ::: - Add manual YAML implementation to drop SnakeYAML dependency. [#3145](https://github.com/iBotPeaches/Apktool/issues/3145) (Thanks sv99) +- Add [Resource Modes](./docs/resource-modes.md) to allow for more control over resource decoding. [#2836](https://github.com/iBotPeaches/Apktool/issues/2836) - Fix regression with detection of sparse resource table. [#3199](https://github.com/iBotPeaches/Apktool/issues/3199) - Fix poisoning of sparse detection via sparse framework. [#3298](https://github.com/iBotPeaches/Apktool/issues/3298) - Fix over-reading the Res Config Flags if size is larger than known. [#3205](https://github.com/iBotPeaches/Apktool/pull/3205)