{"id":51833664,"url":"https://github.com/factionsecurity/faction-mcp","last_synced_at":"2026-07-22T18:30:43.129Z","repository":{"id":351935704,"uuid":"1212117570","full_name":"factionsecurity/faction-mcp","owner":"factionsecurity","description":"MCP server to assist pentesting with Faction","archived":false,"fork":false,"pushed_at":"2026-05-15T16:22:22.000Z","size":597,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-15T19:17:19.229Z","etag":null,"topics":["hacking","mcp-server","pentesting-tools","redteam-tools","vulnerability-management-platform"],"latest_commit_sha":null,"homepage":"https://www.factionsecurity.com","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/factionsecurity.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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-04-16T04:36:28.000Z","updated_at":"2026-05-15T16:22:27.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/factionsecurity/faction-mcp","commit_stats":null,"previous_names":["factionsecurity/faction-mcp"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/factionsecurity/faction-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/factionsecurity%2Ffaction-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/factionsecurity%2Ffaction-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/factionsecurity%2Ffaction-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/factionsecurity%2Ffaction-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/factionsecurity","download_url":"https://codeload.github.com/factionsecurity/faction-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/factionsecurity%2Ffaction-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35773465,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"online","status_checked_at":"2026-07-22T02:00:06.236Z","response_time":124,"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":["hacking","mcp-server","pentesting-tools","redteam-tools","vulnerability-management-platform"],"created_at":"2026-07-22T18:30:41.739Z","updated_at":"2026-07-22T18:30:43.118Z","avatar_url":"https://github.com/factionsecurity.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Faction MCP Server\n\nMCP server for the [Faction](https://github.com/factionsecurity/faction) penetration testing management platform. Exposes assessments, vulnerabilities, retests, and audit logs to any MCP-compatible AI client.\n\n## Prerequisites\n\n- Docker (or Podman) installed\n- A running Faction instance\n- A Faction API key — generate one under your user profile in Faction\n\n---\n\n## Option 1: Docker Desktop MCP Catalog\n\nInstall directly from the Docker Desktop MCP Catalog. Enter your `FACTION_API_KEY` and `FACTION_BASE_URL` when prompted.\n\n---\n\n## Option 2: Docker Compose (Docker or Podman)\n\nThis option works anywhere Docker Compose or Podman Compose is available.\n\n### 1. Configure credentials\n\n```bash\ncp .env.example .env\n```\n\nEdit `.env` and fill in your values:\n\n```env\nFACTION_API_KEY=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\nFACTION_BASE_URL=https://faction.yourcompany.com\n```\n\n#### Optional: shared reports / images directory\n\nThe compose files mount a single host directory into the container at `/app/reports`. By default this is `/tmp`. It serves two purposes:\n\n1. **Downloaded reports** — `get_assessment_report` and `generate_assessment_report` write the PDF/DOCX here, and the host path is returned as `file_path` so the client can open it.\n2. **Image uploads** — `upload_assessment_image` reads files from this directory. The LLM is instructed to `cp` host-side images here first (or save pasted screenshots here), then pass the host path. The server auto-translates `/tmp/foo.png` → `/app/reports/foo.png` internally so the LLM doesn't have to think about the container.\n\nGoing through disk avoids round-tripping a large base64 string through tool arguments, where token-stream drift can corrupt the bytes.\n\nTo use a different host folder, set `FACTION_REPORTS_HOST_DIR` in `.env` to an absolute path:\n\n```env\nFACTION_REPORTS_HOST_DIR=/Users/me/faction-reports\n```\n\n### 2. Build the image\n\n```bash\ndocker compose build\n```\n\nPodman:\n```bash\npodman-compose build\n```\n\n### 3. Configure your MCP client\n\nAdd the following to your MCP client config (e.g. `~/.claude/settings.json` for Claude Code, or `claude_desktop_config.json` for Claude Desktop):\n\n**Docker:**\n```json\n{\n  \"mcpServers\": {\n    \"faction\": {\n      \"command\": \"docker\",\n      \"args\": [\n        \"compose\",\n        \"-f\", \"/absolute/path/to/faction-mcp/docker-compose.yml\",\n        \"run\", \"--rm\", \"-T\", \"faction-mcp\"\n      ]\n    }\n  }\n}\n```\n\n**Podman:**\n```json\n{\n  \"mcpServers\": {\n    \"faction\": {\n      \"command\": \"podman-compose\",\n      \"args\": [\n        \"-f\", \"/absolute/path/to/faction-mcp/docker-compose.yml\",\n        \"run\", \"--rm\", \"-T\", \"faction-mcp\"\n      ]\n    }\n  }\n}\n```\n\n\u003e The `-T` flag disables pseudo-TTY allocation so stdio passes through cleanly to the MCP client.\n\nTo update credentials, edit `.env` — no rebuild required.\n\n---\n\n## Available Tools\n\n### Assessments\n\n| Tool | Description |\n|------|-------------|\n| `get_assessment_queue` | Get the user's active queue (in-progress / upcoming / past-due). Use this for \"my recent assessments\" — not the completed endpoints |\n| `get_completed_assessments` | Get completed assessments within a date range with full detail |\n| `get_completed_assessments_condensed` | Same as above but with large text blocks stripped — preferred for stats and historical summaries |\n| `get_assessment` | Get full details for a specific assessment by ID |\n| `update_assessment` | Update assessment fields: notes, executive summary, distribution list, custom fields |\n| `get_assessment_vulnerabilities` | Get full vulnerability data for an assessment (large response — includes HTML and screenshots) |\n| `get_vulnerability_summary_data` | Get stripped vulnerability data optimized for generating executive summaries |\n| `get_assessment_report` | Download the existing report (PDF/DOCX) for an assessment to the configured reports directory |\n| `generate_assessment_report` | Kick off a fresh report build and poll until it finishes (or until `max_wait_seconds` elapses) |\n| `check_report_status` | Standalone status check used to resume polling when generation outlasts the initial wait |\n\n### Vulnerabilities\n\n| Tool | Description |\n|------|-------------|\n| `get_vulnerabilities` | Get all vulnerabilities opened within a date range with full detail |\n| `get_vulnerabilities_condensed` | Same as above with large text blocks stripped — preferred for stats and summaries |\n| `create_vulnerability` | Add a vulnerability to an assessment. Interactively prompts for missing title/severity, offers matching default templates, and confirms whether to mirror severity to impact/likelihood |\n| `update_vulnerability` | Update fields on an existing vulnerability |\n| `add_templated_vulnerability` | Add a vulnerability from a default template (search with `search_vulnerability_templates` first) |\n| `get_vulnerability` | Get a vulnerability by ID |\n| `get_vulnerability_by_tracking` | Get a vulnerability by tracking ID (e.g. Jira ticket) |\n| `set_vulnerability_tracking` | Assign a tracking ID to a vulnerability |\n| `set_vulnerability_status` | Set remediation status (dev/prod closed dates) |\n| `get_risk_levels` | Get the configured (mapped) risk level definitions; unmapped slots are filtered out |\n| `get_categories` | Get all vulnerability categories |\n| `get_category` | Get a specific category by ID |\n| `create_category` | Create a new vulnerability category (manager role required) |\n\n### Vulnerability Templates\n\n| Tool | Description |\n|------|-------------|\n| `get_vulnerability_templates` | Get all default vulnerability templates |\n| `search_vulnerability_templates` | Search templates by name (partial match) |\n| `get_vulnerability_template` | Get a specific template by ID |\n| `create_vulnerability_templates` | Create or update default vulnerability templates |\n\n### Retests / Verifications\n\n| Tool | Description |\n|------|-------------|\n| `get_verification_queue` | Get the retest queue assigned to the authenticated user |\n| `get_all_verifications` | Get all verifications, optionally filtered by date range |\n| `get_user_verifications` | Get verifications for a specific user |\n| `complete_verification` | Mark a retest as passed or failed |\n| `schedule_retest` | Schedule a retest for a vulnerability |\n\n### Audit Logs\n\n| Tool | Description |\n|------|-------------|\n| `get_audit_log` | Get the system audit log for a date range (admin role required) |\n| `get_assessment_audit_log` | Get audit log entries for all assessments in a date range |\n| `get_assessment_audit_log_by_id` | Get audit log entries for a specific assessment |\n| `get_user_audit_log` | Get audit log entries for a specific user |\n\n---\n\n## Generating Executive Summaries\n\nUse `get_vulnerability_summary_data` (not `get_assessment_vulnerabilities`) when generating executive summaries. It returns clean, stripped text optimized for LLM processing. After the AI generates the summary HTML, it will call `update_assessment` to save it automatically.\n\n## Creating Vulnerabilities\n\n`create_vulnerability` (and `update_vulnerability` / `add_templated_vulnerability`) accept severity, impact, and likelihood as **risk-level NAMES** — e.g. `\"Critical\"`, `\"High\"`, `\"P1\"`. The server resolves the name to the correct numeric ID for your Faction instance using `get_risk_levels`, so the LLM does not have to guess and IDs that differ between instances do not need to be hard-coded.\n\nWhen required information is missing, `create_vulnerability` walks the user through an interactive workflow via MCP elicitation (supported by Claude Code, Claude Desktop, and other elicitation-capable clients):\n\n1. **Title and severity** — if either is missing, the user is prompted for it. Risk levels are presented as a dropdown of the names actually configured on the instance.\n2. **Template offer** — if no `description` / `recommendation` / `vuln_template_id` is supplied, the server searches default templates by the vulnerability title and offers any matches. Picking one auto-populates description and recommendation.\n3. **Mirror severity** — if severity is set but impact/likelihood are not, the server asks whether to use the severity level for both. Pick \"no\" and a follow-up form asks for the explicit impact and likelihood values.\n\nIf the calling client does not support elicitation, the tool returns a clear error listing the missing fields so the LLM can ask the user via plain text instead.\n\n## Generating and Downloading Reports\n\nThere are three tools for working with assessment reports:\n\n- **`generate_assessment_report`** — kicks off a fresh report build (use `retest=true` for finalized assessments) and polls for completion up to `max_wait_seconds` (default 60). When the report is ready, the response says so; if it's still building, the response includes the `gentime` so polling can be resumed.\n- **`check_report_status`** — standalone poll for the case where the initial wait window expired. Pass `last_known_gentime` from the generate response.\n- **`get_assessment_report`** — downloads the existing report (PDF or DOCX). The file is written to the configured reports directory and the absolute host path is returned as `file_path`.\n\nTypical flow:\n\n1. Ask the AI to \"generate a new report for assessment 420.\"\n2. The MCP server fires generation, waits ~60s, and reports completion (or tells the LLM to keep polling for longer-running reports).\n3. Once `status` is `complete`, the AI calls `get_assessment_report` and shares the host file path so the user can open the document.\n\nReports are saved to whichever path you configured via `FACTION_REPORTS_HOST_DIR` (see [reports directory](#optional-reports-directory)). Default: `./faction-reports` next to the compose file.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffactionsecurity%2Ffaction-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffactionsecurity%2Ffaction-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffactionsecurity%2Ffaction-mcp/lists"}