Telegram Mini App Security Auditor

Audit Telegram Mini App projects for launch safety before connecting bot tokens or public channels. Use when Codex needs to review a Telegram WebApp/Mini App...

Security Scan

The skill's files, instructions, and required resources are consistent with a static security auditor for Telegram Mini Apps — it only needs a local run of the included Python script and does not request unrelated credentials or installs.

Purpose & Capability

Name/description match the provided artifacts: SKILL.md, a checklist, report template, and a bundled Python auditor (scripts/audit_tma.py) that implements the checks described. There are no unexplained environment variables, cloud credentials, or unrelated binaries required.

Instruction Scope

SKILL.md instructs a local static scan of project files and to manually inspect flagged files. The instructions do not request reading unrelated system files, secrets, or automatic transmission of results. The doc suggests an optional follow-up (trustclaw) but keeps live Telegram actions out of scope unless explicitly requested.

Install Mechanism

No install spec is provided; the skill is instruction-only with a bundled Python script. Nothing is downloaded from remote URLs at install time. The included script will be run locally by the user (python3 scripts/audit_tma.py), not automatically installed by the registry.

Credentials

The skill declares no required environment variables or credentials. The auditor searches repository files for token-like literals and secrets (expected behavior for a scanner) but does not require access to external keys or config paths.

Persistence & Privilege

always:false and user-invocable:true (no forced persistence). skill-policy.json forbids shell and package installation and restricts network hosts to ["api"] — the skill itself is a local static auditor and does not request persistent privileges.

Assessment

This skill appears coherent and implements a conservative static auditor. Before using it: 1) Inspect scripts/audit_tma.py yourself (it is included) to confirm it only reads files and does not make network calls or write unexpected data. 2) Run the auditor on a local copy of the project, not on a system with live credentials; do not pass real bot tokens. 3) Review any BLOCK/REVIEW findings and manually inspect flagged files before connecting production bot tokens or launching channels. 4) If you plan to run the optional trustclaw step, ensure trustclaw is a trusted tool. 5) Verify the repository homepage and publisher; if the source or author is unfamiliar, run the script in an isolated environment (container or VM) first.

Audit Telegram Mini Apps with a static, evidence-first workflow. Prefer the bundled script for repeatability, then inspect the flagged files before giving launch advice.

Quick Start

Run the static auditor from the skill folder:

python3 {baseDir}/scripts/audit_tma.py \
  /path/to/project \
  --out-dir /tmp/tma-audit

Expected outputs:

• tma_security_audit.json
• tma_security_audit.md

Decision meanings:

• PASS: no blocking or review-triggering evidence found by this static pass.
• REVIEW: launch only after a human verifies the listed risks.
• BLOCK: do not launch or connect production bot tokens until fixed.

Workflow

1. Run scripts/audit_tma.py against the project root or Mini App subdirectory.
2. Read the Markdown report and inspect every BLOCK and REVIEW file reference.
3. If the app is not detected as a Telegram Mini App, confirm whether the user passed the correct path.
4. For production launch, require all of these:
   • server-side Telegram initData validation,
   • no committed bot tokens or token-like literals,
   • admin endpoints protected by server-side authorization,
   • no broad CORS in production,
   • request forms reject or avoid contact details, handles, secrets, and payment terms when governance requires it,
   • local/browser QA evidence before BotFather or channel changes.
5. If packaging as a ClawHub/Codex skill, run TrustClaw after this audit:

trustclaw scan /path/to/skill --format markdown

Finding Triage

Treat script output as static evidence, not a final proof of safety.

• hardcoded-telegram-token: always BLOCK; rotate the token if it was committed.
• initdata-no-server-validation: BLOCK; Mini App users must not be trusted from client-side data alone.
• insecure-initdata-bypass: usually REVIEW; acceptable only for clearly documented local dev commands and disabled-by-default server behavior.
• cors-wildcard: REVIEW, or BLOCK if credentials are also enabled.
• admin-endpoint-without-guard: BLOCK.
• unsafe-innerhtml: REVIEW; verify escaping or sanitization.

For detailed rules and manual checks, read references/tma-security-checklist.md only when needed.

Output Contract

When answering a user, lead with:

1. decision,
2. highest-severity findings with file paths,
3. launch recommendation,
4. artifacts produced,
5. any limitations of the audit.

Keep live Telegram/BotFather/channel changes out of scope unless the user explicitly asks to launch and the project has passed audit and QA.