Metadata-Version: 2.4
Name: masaudit
Version: 0.4.0
Summary: A free mobile security scanner that scales its advice to your app's risk profile.
Author-email: Hossam Atef <hossam9k@gmail.com>
License-Expression: Apache-2.0 AND MIT-0 AND CC-BY-SA-4.0
Project-URL: Homepage, https://github.com/hossam9k/masaudit
Project-URL: Book, https://github.com/hossam9k/mobile-app-security
Project-URL: Sponsor, https://github.com/sponsors/hossam9k
Keywords: security,mobile,android,ios,flutter,masvs,sast,sarif
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: LICENSES/Apache-2.0.txt
License-File: LICENSES/CC-BY-SA-4.0.txt
License-File: LICENSES/MIT-0.txt
Dynamic: license-file

# masaudit

**A free mobile security scanner that scales its advice to your app's risk.**
Point it at an Android, iOS, Kotlin Multiplatform, or Flutter project. It finds the weaknesses that matter
*for your kind of app*, explains each one in plain words, and tells you what you **don't** need.

A news app should never be told to pin certificates. A banking app should. Most scanners give
both the same list.

[![ci](https://github.com/hossam9k/masaudit/actions/workflows/ci.yml/badge.svg)](https://github.com/hossam9k/masaudit/actions/workflows/ci.yml)
[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/hossam9k/masaudit/badge)](https://scorecard.dev/viewer/?uri=github.com/hossam9k/masaudit)
[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/15835/badge)](https://www.bestpractices.dev/projects/15835)
[![PyPI](https://img.shields.io/pypi/v/masaudit)](https://pypi.org/project/masaudit/)
[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue)](https://github.com/hossam9k/masaudit/blob/main/LICENSING.md)

---

## What is masaudit?

masaudit reads the source code of your Android, iOS, Kotlin Multiplatform, or Flutter app and finds security
weaknesses before you ship. It catches traffic sent over plain HTTP, secrets left in the code,
screens other apps can open, weak encryption, risky build settings, and unsafe CI workflows. It
runs on your machine, needs no account, and sends nothing anywhere.

The name is **MAS** + **audit**: it audits your app against
[OWASP MAS](https://mas.owasp.org/) (Mobile Application Security), the standards behind its checks.
masaudit is an independent project, not part of OWASP.

## Why you need it

Most mobile security problems aren't clever attacks. They're settings and code that slipped
through review: a debug flag left on, a test server that accepts any certificate, a token written
to the log. A pentest finds them late and costs money. The app stores don't look for them at all.

Other scanners find these too, but they give every app the same list. A news app gets told to pin
certificates like a bank, which adds outage risk for no gain, and the team learns to ignore the
tool. masaudit first asks what kind of app you're building. Then it sorts every finding into
**fix before release**, **fix soon**, or **not needed for your app**, and says why.

## Who it's for

- **Mobile developers** who want a security check without becoming security experts first.
- **Tech leads** getting ready for a pentest, a security review, or a compliance audit.
- **Security engineers** who want results scaled to each app's risk, in SARIF, on every pull request.

## How it works

1. **You answer one question:** what kind of app is this (banking, health, shop, loyalty, game, …)?
   masaudit saves the answer for next time.
2. **It reads your project:** manifests, Gradle files, `Info.plist`, Xcode projects, Kotlin, Java,
   Swift, Objective-C, and Dart code, and GitHub workflows. It never builds or runs your code.
3. **It writes `SECURITY-AUDIT.md`:** a verdict, the top fixes with paste-ready code, how to check
   each fix worked, and links to OWASP and to a free book that explains every finding.

## Three ways in

| **Scan, no AI needed** | **Fix it with an AI assistant** | **Learn why** |
|---|---|---|
| `uvx masaudit .` | Claude Code: `/plugin marketplace add hossam9k/masaudit` | Every rule links to the free book |
| Offline, Python 3.9+, zero dependencies. Writes `SECURITY-AUDIT.md`. | Audits, triages, fixes one finding at a time, reviews PRs. Works in any [Agent Skills](#use-it-with-an-ai-assistant) tool. | [*Mobile Application Security: A Study Book for Engineers*](https://github.com/hossam9k/mobile-app-security) |

## See it on a real report

The repository ships a deliberately insecure demo app, *Acme Wallet*. Here's the same code
scanned under two profiles:

| | As a **banking** app | As a **news** app |
|---|---|---|
| Fix before release | 12 | 9 |
| Fix soon | 27 | 12 |
| Not needed for your app | 0 | 17: pinning, root and debugger detection, App Attest, Play Integrity, screenshot blocking, … each with the reason |
| Full report | [sample-report-banking.md](https://github.com/hossam9k/masaudit/blob/main/docs/sample-report-banking.md) | [sample-report-news.md](https://github.com/hossam9k/masaudit/blob/main/docs/sample-report-news.md) |

Each finding says **why it matters**, **how to fix it** (with paste-ready code), **how to verify the
fix**, how long it takes, its OWASP IDs (MASWE, the catalog of mobile weaknesses, and MASVS, the
standard's controls), and the book section that explains it.

## Scan without AI

You need Python 3.9 or later (check with `python3 --version`). Run the scan from your project's root
folder, or pass the folder's path. Pick one way to run it:

```bash
uvx masaudit .              # if you have uv: https://docs.astral.sh/uv/
pipx run masaudit .         # if you have pipx: https://pipx.pypa.io/
python3 masaudit.pyz .      # no installer: download masaudit.pyz from the latest release
```

`masaudit.pyz` is one file from the [latest release](https://github.com/hossam9k/masaudit/releases/latest):
it works offline and needs nothing else. To install the command for good, use `pipx install masaudit`.
Plain `pip install masaudit` works inside a virtual environment.

The first run asks one question, **"What kind of app is this?"**, and offers to save your answer in
`.masaudit.ini`. If two types fit, pick the riskier one. The answer maps to OWASP's MAS profiles,
shown in the report: **L1** is the baseline, **L2** adds protection for sensitive data, **R** resists
tampering, and **P** covers privacy.

Without an answer (in CI, for example), it assumes `general` and lists higher-risk checks as
*Not needed*. Set `--app-type` in CI.

The report, `SECURITY-AUDIT.md`, starts with a verdict and the top 3 fixes. Fix those, scan again,
then add masaudit to CI.

### Options

These examples use `masaudit`. If you run it another way, type `uvx masaudit` or
`python3 masaudit.pyz` instead.

```bash
masaudit . --app-type loyalty     # banking, identity, health, ecommerce-cards, ecommerce, loyalty,
                                  # marketplace, social, content, device-control, enterprise, game, general
masaudit . --format sarif --output masaudit.sarif   # SARIF: the format GitHub code scanning reads
masaudit . --fail-on high         # exit 1 on open high or critical findings (exit 2: tool error)
masaudit --explain AND-004        # what a rule checks and how to fix it, offline
masaudit . --fix-safe             # preview automatic fixes as a diff; changes nothing
```

`--fix-safe` applies only fixes that can't change how a correct app behaves. Today that's one:
removing `android:debuggable="true"` from the main manifest. Every other finding has a paste-ready
fix in the report.

### In CI

Add this file as `.github/workflows/masaudit.yml`:

```yaml
name: masaudit
on: [push, pull_request]
permissions: {}
jobs:
  scan:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      security-events: write          # to show results in GitHub code scanning
    steps:
      - uses: actions/checkout@<commit-sha>
        with:
          persist-credentials: false
      - uses: hossam9k/masaudit@<commit-sha> # v0.4.0
        with:
          app-type: banking
          fail-on: high
```

Replace each `<commit-sha>` with the full 40-character commit ID of the release you want: open the
action's Releases page, click the tag, and copy the commit ID. A tag can be moved to other code; a
commit ID can't. Dependabot keeps the IDs current.

The Action runs from its own pinned source, with no download and no network. Results appear in the
repository's Security tab. Pull requests from forks skip the upload.

To scan before every commit, add this to `.pre-commit-config.yaml` ([pre-commit](https://pre-commit.com/)):

```yaml
repos:
  - repo: https://github.com/hossam9k/masaudit
    rev: v0.4.0
    hooks:
      - id: masaudit
        args: [--app-type, banking]
```

### Team features

- **Suppress a finding, with a reason.** Put a comment on the line or the line above. In Kotlin, Java,
  or Swift: `// masaudit:ignore AND-004 test server only, never in release`. In XML:
  `<!-- masaudit:ignore AND-015 reachable only with our signature permission -->`. A suppression
  without a reason is ignored and reported.
- **Accept today's findings in an older app.** `masaudit . --update-baseline` saves the current
  findings to `.masaudit-baseline.json`. Later runs with `--baseline .masaudit-baseline.json` show
  them as *Accepted* and fail only on new ones.
- **Bring your other tools.** `--import-sarif lint.sarif mobsfscan.sarif` sorts Android Lint,
  mobsfscan, Semgrep, and zizmor results by the same app type.

## Use it with an AI assistant

**Claude Code**

```text
/plugin marketplace add hossam9k/masaudit
/plugin install masaudit@masaudit
```

Then `/masaudit:scan`, `/masaudit:fix`, `/masaudit:review`, or `/masaudit:explain AND-004`, or just
ask: *"Is my app ready for a pentest?"*

**Other tools** (Codex, GitHub Copilot, Cursor, Gemini CLI, and other tools that read
[Agent Skills](https://agentskills.io)): copy [`plugin/skills/masaudit/`](https://github.com/hossam9k/masaudit/tree/main/plugin/skills/masaudit) into
your tool's skills folder. The skill bundles the scanner, so it works offline.

**Any chat assistant:** the end of every `SECURITY-AUDIT.md` has a *Fix plan for your AI assistant*.
Paste it in.

The assistant confirms each finding in context, looks for what a scanner can't see (server-side
trust, biometric flows, token handling), and fixes one finding at a time. It asks before any
behavior-changing fix and never commits.

## What it checks

172 rules: 66 Android, 42 iOS, 42 cross-platform code, 8 Flutter, 8 CI and supply chain, 6 Kotlin
Multiplatform. Cross-platform rules read Kotlin, Java, Swift, Objective-C, and Dart. Together they cover
52 of the 78 weaknesses in OWASP's MASWE catalog and cite 132 OWASP MASTG tests. Many of the remaining
weaknesses can't be seen in source code, such as server behavior or a built binary.
See [docs/rules.md](https://github.com/hossam9k/masaudit/blob/main/docs/rules.md).

- **Network:** cleartext (app-wide or per domain), ATS exceptions, user CAs, TLS bypasses in Kotlin, Swift, Dart, and native code, old TLS versions, gRPC plaintext, pinning (only where the profile needs it).
- **Storage:** tokens in SharedPreferences, DataStore, UserDefaults, or shared_preferences; Keychain classes; backups and device-to-device transfer; shared and world-readable files; App Group files; Tink's silent cleartext fallback.
- **Crypto:** hardcoded keys, ECB, CBC without a MAC, fixed IVs and salts, DES/3DES/RC4, small keys, weak PBKDF2, MAC comparison with `==`, keys that both encrypt and sign.
- **Platform:** exported components (knowing which must be public), intent redirection, implicit intents carrying secrets, PendingIntent, deep links, FileProvider, Dirty Stream, Zip Slip, WebView file access and JavaScript bridges, screenshot and overlay protection, clipboard secrets, custom keyboards.
- **Auth:** biometrics not bound to a key, passcode fallback for sensitive actions, keys that survive new enrollments, LocalAuthentication reuse.
- **Privacy:** sensitive permissions, hardware identifiers, IDFA without App Tracking Transparency, privacy manifests and required-reason APIs, tracking domains, personal data sent to analytics.
- **Build and CI:** debuggable or test-only releases, debug tools and DEBUG code in release, R8 and keep rules, signing, unpinned actions (ranked by who owns them), persisted tokens, script injection, committed signing keys.
- **Resilience (MAS-R, only for banking, identity, loyalty, and game apps):** Play Integrity, App Attest, root, debugger, emulator, and hooking detection.

## How accurate it is

Every rule is measured on 19 open-source apps, including Signal, Bitwarden, Wikipedia, Nextcloud,
DuckDuckGo, and Thunderbird. Reviewers who didn't write the rules opened every finding in shipping
code and judged whether it was real. Every false alarm they found was fixed and re-checked.

- **Every rule is at 90% precision or better on this corpus.** The one exception is marked
  *Check by hand*.
- **No crashes** across all 19 apps; the largest scans in under 20 seconds.

The method and per-rule numbers are in [docs/precision.md](https://github.com/hossam9k/masaudit/blob/main/docs/precision.md).

## How it compares

| | masaudit | MobSF | mobsfscan | Android Lint |
|---|---|---|---|---|
| Advice scaled to the app's risk | **Yes** | No | No | No |
| "Not needed for your app", with reasons | **Yes** | No | No | No |
| Plain-language why, fix, and verify per finding | **Yes** | Partly | Partly | Partly |
| Android + iOS + KMP + Flutter + GitHub Actions | **Yes** | Android, iOS (binaries and source) | Android, iOS (source) | Android |
| Install | Single file, no dependencies | Docker (recommended) | pip (Semgrep) | Android SDK |
| Imports the others' SARIF and calibrates it | **Yes** | — | — | — |
| Published precision on real apps | **Yes** | — | — | — |

MobSF also analyzes built APK and IPA files and runs the app for dynamic testing, which masaudit
doesn't. Use both.

## What it can't do

masaudit reads your source and configuration. It can't see your server, runtime behavior, or
business logic, which is where many real breaches happen. Every report ends with a *Residual risk*
section that says so, and lists anything the scanner couldn't decide. Rules marked *Check by hand*
need a human or an AI assistant to confirm.

## Safe to run on any code

masaudit never executes project code, never follows symlinks out of the scan root, refuses XML
entity tricks, makes **no network calls** (a test enforces it), and masks secrets in every output.
No telemetry. See [SECURITY.md](https://github.com/hossam9k/masaudit/blob/main/SECURITY.md).

## Contributing

False-positive reports are the most valuable contribution: a rule that cries wolf gets ignored.
Adding a rule takes about 30 minutes: see [CONTRIBUTING.md](https://github.com/hossam9k/masaudit/blob/main/CONTRIBUTING.md).

## About

Built by **Hossam Atef**, a mobile engineer (Android, iOS, Kotlin Multiplatform), as the practical
companion to his free book,
[*Mobile Application Security: A Study Book for Engineers*](https://github.com/hossam9k/mobile-app-security).
Every rule traces to a section of the book, and the book records how each claim was verified.

masaudit is not an OWASP project; OWASP doesn't certify apps or endorse tools.
Licensing: code Apache-2.0, fix snippets MIT-0, explanations CC BY-SA 4.0. See [LICENSING.md](https://github.com/hossam9k/masaudit/blob/main/LICENSING.md).

masaudit is free. If it saved you an audit, you can [sponsor it](https://github.com/sponsors/hossam9k).
