# mcbottm/mcbotscan architecture

> Architecture diagram of the GitHub repository mcbottm/mcbotscan, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mcbottm/mcbotscan
- Repository: https://github.com/mcbottm/mcbotscan

## Overview

MCBOTSCAN is a Termux-oriented, static APK risk scanner: users provide an APK or decompiled directory and receive scored findings, a risk classification, and optionally JSON. Its main workflow is CLI to scan orchestration, APK extraction and manifest/smali analysis, cluster-based scoring, then reporting. The README also describes captured-log parsing and dynamic-analysis extension stubs; these are separate from the working static workflow. Edges reflect the supplied source excerpts, index references, and README; unsampled behavior is not inferred.

Main entry points: [`mcbotscan/core/scanner.py`](https://github.com/mcbottm/mcbotscan/blob/main/mcbotscan/core/scanner.py) (Scan orchestrator), [`mcbotscan/static/string_scan.py`](https://github.com/mcbottm/mcbotscan/blob/main/mcbotscan/static/string_scan.py) (Smali scanning), [`mcbotscan/core/analyzer.py`](https://github.com/mcbottm/mcbotscan/blob/main/mcbotscan/core/analyzer.py) (Risk analysis), [`mcbotscan/static/yara_engine.py`](https://github.com/mcbottm/mcbotscan/blob/main/mcbotscan/static/yara_engine.py) (YARA scanning)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interface"]
  node_cli["CLI<br/>[main.py]"]
  node_package_api["Package API<br/>[__init__.py]"]
end

subgraph group_pipeline["Scan pipeline"]
  node_scanner["Scan orchestrator<br/>[scanner.py]"]
  node_extractor["APK extraction<br/>[extractor.py]"]
end

subgraph group_detection["Detection and scoring"]
  node_permission_scan["Manifest scanning<br/>[permission_scan.py]"]
  node_string_scan["Smali scanning<br/>[string_scan.py]"]
  node_dex_loader["DEX patterns<br/>[dex_loader.py]"]
  node_yara["YARA scanning<br/>[yara_engine.py]"]
  node_rules["Detection rules"]
  node_analyzer["Risk analysis<br/>[analyzer.py]"]
end

subgraph group_results["Results and utilities"]
  node_report["Report renderer<br/>[report.py]"]
  node_sha["APK hashing<br/>[hash.py]"]
  node_logger["Scan logging<br/>[logger.py]"]
  node_helpers["Scan helpers<br/>[helpers.py]"]
  node_version["Version metadata<br/>[_version.py]"]
end

subgraph group_behavioral["Behavioral extensions"]
  node_logcat["Logcat parser<br/>[logcat_parser.py]"]
  node_network_stub["Network monitor stub<br/>[network_monitor.py]"]
  node_hooks_stub["Emulator hooks stub<br/>[emulator_hooks.py]"]
end

node_user(("APK analyst"))

node_user -->|"provides target"| node_cli
node_cli -->|"imports"| node_package_api
node_package_api -->|"exposes scanner"| node_scanner
node_scanner -->|"extracts APK"| node_extractor
node_scanner -->|"scans manifest"| node_permission_scan
node_scanner -->|"scans smali"| node_string_scan
node_scanner -->|"runs optional scan"| node_yara
node_scanner -->|"loads rules"| node_rules
node_string_scan -->|"delegates patterns"| node_dex_loader
node_yara -->|"discovers smali dirs"| node_extractor
node_yara -->|"creates findings"| node_analyzer
node_scanner -->|"scores findings"| node_analyzer
node_scanner -->|"renders results"| node_report
node_scanner -->|"hashes target"| node_sha
node_scanner -->|"logs scan"| node_logger
node_permission_scan -->|"creates findings"| node_analyzer
node_string_scan -->|"creates findings"| node_analyzer
node_string_scan -->|"classifies URLs"| node_helpers
node_report -->|"reads version"| node_version
node_report -->|"formats points"| node_helpers

click node_cli "https://github.com/mcbottm/mcbotscan/blob/main/cli/main.py"
click node_package_api "https://github.com/mcbottm/mcbotscan/blob/main/mcbotscan/__init__.py"
click node_scanner "https://github.com/mcbottm/mcbotscan/blob/main/mcbotscan/core/scanner.py"
click node_extractor "https://github.com/mcbottm/mcbotscan/blob/main/mcbotscan/core/extractor.py"
click node_permission_scan "https://github.com/mcbottm/mcbotscan/blob/main/mcbotscan/static/permission_scan.py"
click node_string_scan "https://github.com/mcbottm/mcbotscan/blob/main/mcbotscan/static/string_scan.py"
click node_dex_loader "https://github.com/mcbottm/mcbotscan/blob/main/mcbotscan/static/dex_loader.py"
click node_yara "https://github.com/mcbottm/mcbotscan/blob/main/mcbotscan/static/yara_engine.py"
click node_rules "https://github.com/mcbottm/mcbotscan/tree/main/mcbotscan/rules"
click node_analyzer "https://github.com/mcbottm/mcbotscan/blob/main/mcbotscan/core/analyzer.py"
click node_report "https://github.com/mcbottm/mcbotscan/blob/main/mcbotscan/core/report.py"
click node_sha "https://github.com/mcbottm/mcbotscan/blob/main/mcbotscan/utils/hash.py"
click node_logger "https://github.com/mcbottm/mcbotscan/blob/main/mcbotscan/utils/logger.py"
click node_helpers "https://github.com/mcbottm/mcbotscan/blob/main/mcbotscan/utils/helpers.py"
click node_version "https://github.com/mcbottm/mcbotscan/blob/main/mcbotscan/_version.py"
click node_logcat "https://github.com/mcbottm/mcbotscan/blob/main/mcbotscan/behavioral/logcat_parser.py"
click node_network_stub "https://github.com/mcbottm/mcbotscan/blob/main/mcbotscan/behavioral/network_monitor.py"
click node_hooks_stub "https://github.com/mcbottm/mcbotscan/blob/main/mcbotscan/behavioral/emulator_hooks.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_package_api toneBlue
class node_scanner,node_extractor toneAmber
class node_permission_scan,node_string_scan,node_dex_loader,node_yara,node_rules,node_analyzer toneMint
class node_report,node_sha,node_logger,node_helpers,node_version toneRose
class node_logcat,node_network_stub,node_hooks_stub,node_user toneIndigo
```

## Components

### User interface

- [CLI](https://github.com/mcbottm/mcbotscan/blob/main/cli/main.py): `cli/main.py`
- [Package API](https://github.com/mcbottm/mcbotscan/blob/main/mcbotscan/__init__.py): `mcbotscan/__init__.py`

### Scan pipeline

- [Scan orchestrator](https://github.com/mcbottm/mcbotscan/blob/main/mcbotscan/core/scanner.py): `mcbotscan/core/scanner.py`
- [APK extraction](https://github.com/mcbottm/mcbotscan/blob/main/mcbotscan/core/extractor.py): `mcbotscan/core/extractor.py`

### Detection and scoring

- [Manifest scanning](https://github.com/mcbottm/mcbotscan/blob/main/mcbotscan/static/permission_scan.py): `mcbotscan/static/permission_scan.py`
- [Smali scanning](https://github.com/mcbottm/mcbotscan/blob/main/mcbotscan/static/string_scan.py): `mcbotscan/static/string_scan.py`
- [DEX patterns](https://github.com/mcbottm/mcbotscan/blob/main/mcbotscan/static/dex_loader.py): `mcbotscan/static/dex_loader.py`
- [YARA scanning](https://github.com/mcbottm/mcbotscan/blob/main/mcbotscan/static/yara_engine.py): `mcbotscan/static/yara_engine.py`
- [Detection rules](https://github.com/mcbottm/mcbotscan/tree/main/mcbotscan/rules): `mcbotscan/rules`
- [Risk analysis](https://github.com/mcbottm/mcbotscan/blob/main/mcbotscan/core/analyzer.py): `mcbotscan/core/analyzer.py`

### Results and utilities

- [Report renderer](https://github.com/mcbottm/mcbotscan/blob/main/mcbotscan/core/report.py): `mcbotscan/core/report.py`
- [APK hashing](https://github.com/mcbottm/mcbotscan/blob/main/mcbotscan/utils/hash.py): `mcbotscan/utils/hash.py`
- [Scan logging](https://github.com/mcbottm/mcbotscan/blob/main/mcbotscan/utils/logger.py): `mcbotscan/utils/logger.py`
- [Scan helpers](https://github.com/mcbottm/mcbotscan/blob/main/mcbotscan/utils/helpers.py): `mcbotscan/utils/helpers.py`
- [Version metadata](https://github.com/mcbottm/mcbotscan/blob/main/mcbotscan/_version.py): `mcbotscan/_version.py`

### Behavioral extensions

- [Logcat parser](https://github.com/mcbottm/mcbotscan/blob/main/mcbotscan/behavioral/logcat_parser.py): `mcbotscan/behavioral/logcat_parser.py`
- [Network monitor stub](https://github.com/mcbottm/mcbotscan/blob/main/mcbotscan/behavioral/network_monitor.py): `mcbotscan/behavioral/network_monitor.py`
- [Emulator hooks stub](https://github.com/mcbottm/mcbotscan/blob/main/mcbotscan/behavioral/emulator_hooks.py): `mcbotscan/behavioral/emulator_hooks.py`

### Other components

- **APK analyst**

## Connections

- APK analyst → CLI: provides target (evidence: `README.md`)
- CLI → Package API: imports (evidence: `cli/main.py`)
- Package API → Scan orchestrator: exposes scanner (evidence: `mcbotscan/__init__.py`)
- Scan orchestrator → APK extraction: extracts APK (evidence: `mcbotscan/core/scanner.py`)
- Scan orchestrator → Manifest scanning: scans manifest (evidence: `mcbotscan/core/scanner.py`)
- Scan orchestrator → Smali scanning: scans smali (evidence: `mcbotscan/core/scanner.py`)
- Scan orchestrator → YARA scanning: runs optional scan (evidence: `mcbotscan/core/scanner.py`)
- Scan orchestrator → Detection rules: loads rules (evidence: `mcbotscan/core/scanner.py`)
- Smali scanning → DEX patterns: delegates patterns (evidence: `mcbotscan/static/string_scan.py`)
- YARA scanning → APK extraction: discovers smali dirs (evidence: `mcbotscan/static/yara_engine.py`)
- YARA scanning → Risk analysis: creates findings (evidence: `mcbotscan/static/yara_engine.py`)
- Scan orchestrator → Risk analysis: scores findings (evidence: `mcbotscan/core/scanner.py`)
- Scan orchestrator → Report renderer: renders results (evidence: `mcbotscan/core/scanner.py`)
- Scan orchestrator → APK hashing: hashes target (evidence: `mcbotscan/core/scanner.py`)
- Scan orchestrator → Scan logging: logs scan (evidence: `mcbotscan/core/scanner.py`)
- Manifest scanning → Risk analysis: creates findings (evidence: `mcbotscan/static/permission_scan.py`)
- Smali scanning → Risk analysis: creates findings (evidence: `mcbotscan/static/string_scan.py`)
- Smali scanning → Scan helpers: classifies URLs (evidence: `mcbotscan/static/string_scan.py`)
- Report renderer → Version metadata: reads version (evidence: `mcbotscan/core/report.py`)
- Report renderer → Scan helpers: formats points (evidence: `mcbotscan/core/report.py`)
