Anno 117 Mod Manager is designed with security as a priority, especially given its role in handling untrusted community-created mods. This document outlines the security measures in place and best practices for users.

Your mod.io API key is stored securely:

1. Primary (Recommended): OS credential store via the keyring library

   • Windows: Windows Credential Manager
   • macOS: Keychain
   • Linux: Secret Service (if available)

2. Fallback: Local JSON config file (~/.anno117_mod_manager_config.json)

   • Written with strict permissions (0o600 — read/write for owner only)
   • Never world-readable, even transiently
   • Should never be shared or committed to version control

The .anno117_mod_manager_config.json file is explicitly excluded from git tracking to prevent accidental credential leaks. Never commit this file by accident.

If you suspect your API key has been compromised:

1. Immediately revoke it at https://mod.io
2. Generate a new key
3. Delete the local config file: ~/.anno117_mod_manager_config.json
4. Re-enter your key on next app launch

⚠️ WARNING: Community mods can contain malware

Mods are user-created and untrusted by default. Follow these practices:

• Only install from trusted creators — Check mod.io ratings, reviews, and creator history
• Inspect mod contents — Before enabling, verify mods contain only game data files (.xml, .cfg, .rda, .fc, etc.), not executables (.exe, .dll, .so, .msi)
• Read the mod description — Legitimate creators explain what their mods do
• Disable suspicious mods immediately — If a mod causes crashes, corrupts saves, or seems malicious, uninstall it

This tool includes protections against several common attack vectors:

• Zip Slip / Path Traversal: All mod archives are validated to prevent files escaping the mod folder
• Zip Bombs / Decompression Attacks: Extraction is limited to 2 GB per mod
• Symlink Abuse: Symlinks inside mods are skipped (not extracted)
• Malicious Permissions: Execute bits are stripped from all extracted files (mods are data only)
• File Corruption: Integrity checks before installation; atomic rollback on failure

⚠️ These protections guard against accidental data corruption and zip-based attacks, but cannot prevent malware logic inside mod files. A malicious mod creator could still distribute code that corrupts your game, steals save files, etc. Trust is the primary defense.

This tool does not protect against:

• Malicious mod logic — A mod designed to corrupt game data or player saves
• Social engineering — Fake mods wearing a trusted creator's name
• Supply-chain attacks — A previously-safe mod updated with malware
• Network-based attacks — If a mod connects to the internet to exfiltrate data

Use your judgment. When in doubt, don't install it.

This project depends on:

• requests — HTTP library for communicating with mod.io API
• Pillow — Image library for thumbnail display (optional; gracefully degrades if missing)
• sv-ttk — GUI theming library (optional; uses default Tk theme if missing)
• keyring — OS credential management (optional; falls back to plaintext config if missing)

All dependencies are open-source and commonly used. Check requirements.txt for version constraints.

If you discover a security vulnerability:

1. Do NOT open a public GitHub issue — Disclose privately
2. Email the maintainer — Report with as much detail as possible about the issue and steps to reproduce
3. Allow time for a fix — Reputable maintainers will acknowledge within 48 hours

For now, security reports can be sent via direct message or issue comment marked [SECURITY].

The source code is fully open and available for auditing. Key security-relevant functions:

• _safe_extract() — Zip extraction with path-traversal and zip-bomb protections
• download_mod() — File download with size limits and stream verification
• atomic_json_write() — Secure config writing with temp-file swap and permission hardening
• sanitize_filename() — Cross-platform filename safety, avoiding reserved device names

This tool does not:

• Send telemetry
• Track user activity
• Phone home or connect to external services (except mod.io API, which you explicitly authorize)
• Store sensitive data anywhere except your local machine
• Require internet access to run (mod fetching requires internet, but the tool itself does not)

Check releases periodically for security updates. Update via:

git pull origin main

or re-download the latest .zip from Releases.

Last Updated: February 27, 2026