{"id":51387776,"url":"https://github.com/vicnesterenko/mac-malware-analysis","last_synced_at":"2026-07-03T21:05:56.893Z","repository":{"id":367340474,"uuid":"1279514618","full_name":"vicnesterenko/mac-malware-analysis","owner":"vicnesterenko","description":"App for static macOS malware analysis","archived":false,"fork":false,"pushed_at":"2026-06-25T14:20:02.000Z","size":53,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"test-branch","last_synced_at":"2026-06-25T16:12:02.812Z","etag":null,"topics":["fastapi","malware-analysis"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vicnesterenko.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-24T19:00:42.000Z","updated_at":"2026-06-25T14:20:54.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/vicnesterenko/mac-malware-analysis","commit_stats":null,"previous_names":["vicnesterenko/mac-malware-analysis"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/vicnesterenko/mac-malware-analysis","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vicnesterenko%2Fmac-malware-analysis","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vicnesterenko%2Fmac-malware-analysis/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vicnesterenko%2Fmac-malware-analysis/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vicnesterenko%2Fmac-malware-analysis/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vicnesterenko","download_url":"https://codeload.github.com/vicnesterenko/mac-malware-analysis/tar.gz/refs/heads/test-branch","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vicnesterenko%2Fmac-malware-analysis/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35101151,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-03T02:00:05.635Z","response_time":110,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["fastapi","malware-analysis"],"created_at":"2026-07-03T21:05:56.752Z","updated_at":"2026-07-03T21:05:56.878Z","avatar_url":"https://github.com/vicnesterenko.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Mac Malware Analysis\n\nA lightweight FastAPI web application for safe, static analysis of suspicious macOS-related files.\nUpload a file through the browser or REST API and receive a structured analysis report — no execution, no shell commands, no dynamic behavior.\n\n---\n\n## Why this project exists\n\nmacOS malware triage usually requires a mix of CLI tools, proprietary sandboxes, and manual pattern matching.\nThis project provides a focused, portable, self-hosted triage tool that covers the most common static signals:\nhashes, string extraction, persistence indicators, YARA scanning, and an explainable risk score.\nIt is designed as a learning and portfolio project for junior malware analysts and security engineers.\n\n---\n\n## Main features\n\n| Feature | Details |\n|---------|---------|\n| File upload | Drag-and-drop web UI or REST API |\n| Hashing | MD5, SHA-1, SHA-256 |\n| File-type detection | libmagic + header fallback |\n| String extraction | Printable ASCII and UTF-16LE |\n| Indicator extraction | URLs, domains, IPs, emails, macOS paths |\n| Suspicious commands | curl, wget, osascript, security, base64, chmod +x, shell -c |\n| Persistence detection | LaunchAgent, LaunchDaemon, launchctl, cron, shell profiles |\n| YARA scanning | Three built-in educational rules; gracefully skipped if yara-python is missing |\n| Risk scoring | Transparent, reason-per-factor, 0–100 heuristic scale |\n| JSON report | Downloadable, stored in `reports/` |\n| HTML result page | Colour-coded by risk level |\n\n---\n\n## Safety guarantees\n\n- Uploaded files are **never executed**, imported, or unpacked.\n- No `subprocess` calls on uploaded content.\n- Filenames are sanitized; a random UUID is used for temporary storage.\n- Temporary files are deleted in a `finally` block immediately after analysis.\n- Only the generated JSON report is stored.\n- Report downloads are protected against path-traversal attacks.\n- File contents are never logged.\n\n---\n\n## Architecture\n\n```\napp/\n  main.py           FastAPI application, middleware, exception handlers\n  config.py         Settings loaded from environment / .env\n  models.py         Pydantic response models\n  helpers.py        Logging configuration\n  routes/\n    web.py          HTML routes: GET /, POST /analyze\n    analysis.py     API routes: POST /api/analyze, GET /api/reports/{id}\n  services/\n    analyzer.py     Orchestrates all analysis steps\n    file_validation.py  Size and filename validation\n    hashing.py      MD5 / SHA-1 / SHA-256\n    file_type.py    libmagic + header detection\n    string_extractor.py  ASCII and UTF-16LE extraction\n    indicators.py   URL, IP, email, path, command patterns\n    persistence.py  LaunchAgent / LaunchDaemon / cron patterns\n    yara_scanner.py YARA scanning with graceful fallback\n    risk_engine.py  Heuristic scoring with per-reason breakdown\n    report_service.py   JSON report save / load\n  templates/        Jinja2 HTML templates\n  static/           CSS stylesheet\nrules/              YARA rules (three educational rules)\nsafe_samples/       Harmless demonstration files\nreports/            Generated JSON reports (gitignored except .gitkeep)\ntests/              pytest test suite\n```\n\n---\n\n## Local installation on macOS\n\n```bash\n# 1. Install libmagic\nbrew install libmagic\n\n# 2. Clone the repository\ngit clone https://github.com/your-username/mac-malware-analysis.git\ncd mac-malware-analysis\n\n# 3. Create virtual environment\npython3 -m venv .venv\nsource .venv/bin/activate\n\n# 4. Install dependencies\npip install -r requirements.txt\n\n# 5. Run the server\nuvicorn app.main:app --reload\n```\n\nOpen http://localhost:8000 in your browser.\n\n---\n\n## Local installation on Linux\n\n```bash\n# Install system dependencies\nsudo apt-get install -y libmagic1\n\n# Then follow the macOS steps from step 2 above\n```\n\n---\n\n## Running with Docker\n\n```bash\n# Build and start\ndocker compose up --build\n\n# Stop\ndocker compose down\n```\n\nThe application will be available at http://localhost:8000.\nReports are stored in `./reports/` on your host machine via a volume mount.\n\n---\n\n## Web usage\n\n1. Open http://localhost:8000\n2. Drag and drop a file or click to browse.\n3. Click **Analyze File**.\n4. Review the colour-coded result page.\n5. Click **Download JSON Report** to save the full report.\n\n---\n\n## API usage\n\n### Analyze a file\n\n```bash\ncurl -X POST \\\n  -F \"file=@safe_samples/suspicious_demo.sh\" \\\n  http://localhost:8000/api/analyze\n```\n\n### Download a report\n\n```bash\ncurl http://localhost:8000/api/reports/\u003creport_id\u003e \\\n  -o report.json\n```\n\n### Health check\n\n```bash\ncurl http://localhost:8000/healthcheck\n```\n\nInteractive API docs: http://localhost:8000/docs\n\n---\n\n## Example JSON response\n\n```json\n{\n  \"report_id\": \"a3b4c5d6e7f8...\",\n  \"filename\": \"suspicious_demo.sh\",\n  \"size_bytes\": 321,\n  \"file_type\": {\n    \"description\": \"POSIX shell script, ASCII text executable\",\n    \"mime_type\": \"text/x-shellscript\"\n  },\n  \"hashes\": {\n    \"md5\": \"...\",\n    \"sha1\": \"...\",\n    \"sha256\": \"...\"\n  },\n  \"indicators\": {\n    \"urls\": [\"https://update.example.invalid/payload\"],\n    \"domains\": [\"update.example.invalid\"],\n    \"ipv4_addresses\": [],\n    \"emails\": [],\n    \"file_paths\": [\"/Library/LaunchAgents/com.example.demo.plist\"],\n    \"suspicious_commands\": [\"chmod_executable\", \"curl\", \"security_password_access\", \"shell_execute\"]\n  },\n  \"persistence\": {\n    \"detected\": true,\n    \"findings\": [\n      {\n        \"technique\": \"user_launch_agent\",\n        \"evidence\": [\"$HOME/Library/LaunchAgents/\"],\n        \"confidence\": \"medium\"\n      }\n    ]\n  },\n  \"yara\": {\n    \"enabled\": true,\n    \"available\": true,\n    \"matches\": [\n      {\n        \"rule\": \"MacOS_Persistence_References\",\n        \"meta\": { \"severity\": \"high\", \"description\": \"...\" },\n        \"tags\": []\n      }\n    ],\n    \"errors\": []\n  },\n  \"risk\": {\n    \"score\": 100,\n    \"level\": \"high\",\n    \"reasons\": [\n      { \"code\": \"yara:MacOS_Persistence_References\", \"points\": 30, \"description\": \"High-severity YARA rule matched.\" },\n      { \"code\": \"macos_persistence\", \"points\": 20, \"description\": \"Reference to a LaunchAgent or LaunchDaemon path.\" },\n      { \"code\": \"credential_access\", \"points\": 20, \"description\": \"macOS Keychain access command detected.\" },\n      { \"code\": \"download_execute\", \"points\": 20, \"description\": \"Download and execution commands appear together.\" },\n      { \"code\": \"network_indicators\", \"points\": 2, \"description\": \"Suspicious URLs extracted from the file.\" }\n    ],\n    \"disclaimer\": \"This heuristic score does not prove that a file is malicious.\"\n  }\n}\n```\n\n---\n\n## Running tests\n\n```bash\n# Activate virtual environment first\nsource .venv/bin/activate\n\n# Run all tests\npytest -v\n\n# Run with coverage\npytest --cov=app --cov-report=term-missing\n```\n\n---\n\n## YARA installation notes\n\n`yara-python` requires the YARA C library.\n\n**macOS:**\n```bash\nbrew install yara\npip install yara-python\n```\n\n**Linux:**\n```bash\nsudo apt-get install -y libyara-dev\npip install yara-python\n```\n\n**Docker:** The Dockerfile installs `libmagic1` but not the YARA C library, because `yara-python`'s binary wheel often bundles it.\nIf YARA scanning is unavailable, the analysis still completes and `yara.available` will be `false` in the response.\n\n---\n\n## Known limitations\n\n- Static analysis only: runtime behavior is not observed.\n- Mach-O parsing is limited to header-based type detection (no `otool` or `nm` wrapping).\n- YARA rules are educational and not a comprehensive signature set.\n- ZIP, DMG, PKG, and application bundles are not unpacked.\n- No authentication: suitable for local or internal network use only.\n- Maximum upload size is 20 MB.\n\n---\n\n## False-positive considerations\n\nStatic indicators frequently match legitimate software:\n\n- Developer tools reference `LaunchAgents` paths.\n- Updater scripts use `curl` and `chmod +x`.\n- Backup software accesses the Keychain.\n- High entropy appears in compiled binaries and compressed assets.\n\nAlways interpret the risk score alongside context. It is a triage signal, not a verdict.\n\n---\n\n## Ethical-use notice\n\nThis tool is designed for defensive security research, malware triage, and education.\n\n- Do not upload files belonging to others without authorization.\n- Do not use this tool to analyze files obtained illegally.\n- The author accepts no liability for misuse.\n\n---\n\n\n## Running from any directory\n\nTemplate, static, report, temporary upload, and YARA paths are resolved from the\nproject location rather than the shell's current working directory.\n\nThe recommended command is:\n\n```bash\ncd mac-malware-analysis\nuvicorn app.main:app --reload\n```\n\nRunning `python app/main.py` is also supported.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvicnesterenko%2Fmac-malware-analysis","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvicnesterenko%2Fmac-malware-analysis","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvicnesterenko%2Fmac-malware-analysis/lists"}