✨ feat: install graphviz binaries

[Marco Russo (marcorusso97)]

Context

FC-Attack requires Graphviz to render flowchart images. In restricted environments (no admin privileges), installing Graphviz system-wide is often not possible. This PR introduces a robust local-binary workflow so FC-Attack can run without OS-level installation.

What Changed

• Added automatic dot resolution logic:
  • Use HACKAGENT_GRAPHVIZ_DOT if provided
  • Otherwise use dot from PATH
  • Otherwise download the latest official Graphviz binaries and use them locally
• Added OS-aware persistent storage for Graphviz binaries:
  • Linux and macOS: ~/.local/share/hackagent/graphviz (or $XDG_DATA_HOME/hackagent/graphviz)
  • Windows: %LOCALAPPDATA%/hackagent/graphviz
• Updated hackagent init with Graphviz preflight:
  • Probe without download first
  • Prompt user for consent if Graphviz is missing
  • Prefetch and setup local binaries if accepted
• Added macOS hardening:
  • Prefer .pkg release asset over .zip
  • ZIP extraction with symlink preservation
  • Auto-repair broken .dylib symlink placeholders from previous extractions
  • Patch local install names for pkg-extracted binaries
  • Runtime library environment setup for local execution
  • PNG rendering fallback order on macOS: -Tpng:quartz, then -Tpng
• Improved runtime and fallback error handling in the FC renderer
• Removed HACKAGENT_GRAPHVIZ_CACHE_DIR (path selection is now OS-driven)

User Impact

• FC-Attack can now run without installing Graphviz at system level
• First use may download and prepare local Graphviz binaries
• Setup is now guided from hackagent init with explicit user consent

Tests

Added dedicated unit tests for Graphviz bootstrap behavior:

• OS asset selection (including macOS .pkg preference)
• Download-disabled resolution path
• allow_download flag forwarding
• OS-specific persistent directory resolution (Linux, macOS, Windows)
• macOS dylib symlink repair
• ZIP extraction with symlink preservation

Executed:

• tests/unit/attacks/fc/test_graphviz_bootstrap.py
• tests/unit/attacks/fc/test_serializers.py
• Smoke test via tools/test_fc.py

Notes

This PR resolves no-admin Graphviz setup for FC-Attack and stabilizes local macOS execution for downloaded Graphviz bundles.

[Copilot]

Pull request overview

Adds a local-binary bootstrap for Graphviz so FC-Attack can render flowchart images even when dot isn’t installed system-wide, and integrates an interactive preflight/prefetch step into hackagent init.

Changes:

• Implemented dot resolution with fallbacks: env override → PATH → (optionally) download portable Graphviz bundles into an OS-specific persistent directory.
• Hardened macOS handling (pkg preference, dylib symlink repair, install-name patching, runtime env setup) and improved renderer fallback/error behavior.
• Added unit tests and updated FC-Attack documentation for the new Graphviz behavior.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.

File	Description
tests/unit/attacks/fc/test_graphviz_bootstrap.py	Adds unit tests for asset selection, data dir resolution, dylib symlink repair, and ZIP extraction behavior.
hackagent/cli/main.py	Extends hackagent init to check for Graphviz and optionally prefetch portable binaries with user consent.
hackagent/attacks/techniques/fc/flowchart_renderer.py	Adds Graphviz bootstrap/download/extraction logic and updates rendering to use the resolved dot binary and runtime env.
docs/docs/attacks/fc.md	Documents the new “no-admin Graphviz” workflow and environment variables.

Comments suppressed due to low confidence (1)

hackagent/attacks/techniques/fc/flowchart_renderer.py:497

• Portable binaries are downloaded and extracted without any integrity verification (e.g., comparing against the release-provided .sha256 assets). If the release endpoint, redirect, or network path is compromised, this becomes a remote code execution vector. Consider verifying the archive checksum (or pinning to a known version) before extraction.

        archive_path = install_root / asset_name
        logger.info("Downloading Graphviz archive: %s", asset_name)
        _download_file(asset_url, archive_path)

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[codecov]

Codecov Report

❌ Patch coverage is 80.41237% with 95 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...kagent/attacks/techniques/fc/flowchart_renderer.py	80.53%	88 Missing ⚠️
hackagent/cli/main.py	78.78%	7 Missing ⚠️

📢 Thoughts on this report? Let us know!

[Nicola Franco (franconicola)]

LGTM