frameseven

module
v0.4.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 20, 2026 License: MIT

README

frameseven

A CLI-first offensive web security scanner for authorized security testing.

frameseven maps a target's attack surface and runs active checks for common web vulnerabilities and misconfigurations, then produces structured reports. It also ships an MCP server so AI agents can drive the same Framework v1 tooling.

Go License Version

[!WARNING] Only scan systems that you own or have explicit permission to test. Framework v1 performs active requests and may send methods or payloads that affect a target application.

Features

  • Attack-surface mapping — recon, crawling, port and banner discovery, and subdomain enumeration before any active probing.
  • Active vulnerability checks — XSS, SQL injection, LFI, SSRF, SSTI, XXE, command injection, open redirect, access control, and rate-limit testing.
  • Misconfiguration and content audits — security headers, exposed content, and external resource review.
  • Structured reporting — generates reports under a configurable output directory, with optional PDF rendering.
  • Authenticated scans — -auth-browser opens a browser to log in before the scan so authenticated surface is covered.
  • MCP server — exposes versioned Framework v1 tools to AI agents over stdio or Streamable HTTP.
  • Standard-library focused — a small, explicit Go codebase that is easy to read and extend.

Requirements

  • Go 1.26.4 or later in the Go 1.26 release line
  • Python 3 with fpdf2 for PDF report generation
  • Git
  • Network access to the authorized target
  • Linux, macOS, or another environment supported by Go

Quick Start

git clone https://github.com/sayseven7/frameseven.git
cd frameseven

# Optional: enable PDF report generation
python3 -m venv .venv
.venv/bin/python -m pip install "fpdf2>=2.8"

# Verify the build
go test ./...

# Run a scan against an authorized target
go run cmd/cli/v1/main.go -url https://target.example

Run without -url in a terminal to open the interactive setup wizard:

go run cmd/cli/v1/main.go

Build an installable binary:

go build -o bin/frameseven/cli/v1 cmd/cli/v1/main.go
./bin/frameseven/cli/v1 -url https://target.example

Usage

frameseven -url https://target.example [flags]
Flag Default Description
-url required Absolute HTTP or HTTPS target URL
-tools default Comma-separated Framework v1 tools to run, default, or all
-timeout 10s Timeout applied to each HTTP request
-tool-timeout 30s Maximum runtime for each scanner tool
-concurrency 1 Scanner tools to run in parallel after recon
-rate 50 Requests sent by the rate-limit tool
-ua random agent User-Agent header sent by the scanner
-out, -o reports Directory for generated reports and the scan log
-interactive, -i disabled Configure the scan with an interactive wizard
-yes, -y disabled Skip the wizard's final confirmation
-auth-browser disabled Open a browser to log in before the scan
-quiet, -q disabled Hide banner and progress messages
-verbose, -v disabled Show HTTP request and response debug logs
-list-tools disabled List all Framework v1 scanner tools
-version disabled Print the installed build version

See CLI v1 for the complete flag reference and environment variables.

Scanner tools

recon, crawler, ports, bannergrab, subdomain, external, content, misconfig, access, auth, xss, sqli, lfi, ssrf, ssti, xxe, cmdi, redirect, ratelimit.

List them at any time:

frameseven -list-tools

Reports

PDF reports are rendered by the Go wrapper through Python. The wrapper uses FRAMESEVEN_PYTHON when set, otherwise it looks for .venv/bin/python, then falls back to python3. If Python or fpdf2 is missing, PDF generation returns a clear error instead of silently producing a broken report.

See Report Format v1 for the output contract.

MCP Server

frameseven includes an MCP server at cmd/mcp that exposes versioned Framework v1 tools to AI agents.

# stdio transport
go run ./cmd/mcp -transport stdio

# Streamable HTTP transport
go run ./cmd/mcp -transport http -addr 127.0.0.1:8080

[!CAUTION] Scanner tools send active security probes. Do not expose the HTTP MCP endpoint openly to the internet; place it behind an access-controlled network, reverse proxy, tunnel, or firewall rule.

See MCP Server and MCP configuration for client setup.

Documentation

Contributing

Contributions are welcome. Please read CONTRIBUTING.md and the Code of Conduct before opening a pull request. Project conventions and agent rules live in AGENTS.md.

License

Released under the MIT License.

Directories

Path Synopsis
cmd
cli/v1 command
Package main implements the frameseven CLI v1 entry point.
 Package main implements the frameseven CLI v1 entry point.
mcp command
Package main implements the frameseven MCP server entry point.
 Package main implements the frameseven MCP server entry point.
internal
config
Package config defines the scan configuration and provides a factory that applies project-level defaults for timeout, user agent, and rate limits.
 Package config defines the scan configuration and provides a factory that applies project-level defaults for timeout, user agent, and rate limits.
cve
Package cve maps detected technology versions to known CVEs using the public NVD API 2.0.
 Package cve maps detected technology versions to known CVEs using the public NVD API 2.0.
engagement
Package engagement keeps a persistent record of every finding gathered during an assessment: scanner output plus manual work (dumps, cracked credentials, exfiltrated files).
 Package engagement keeps a persistent record of every finding gathered during an assessment: scanner output plus manual work (dumps, cracked credentials, exfiltrated files).
finding
Package finding defines the finding model used across all framework tools.
 Package finding defines the finding model used across all framework tools.
mcp
Package mcp exposes the FrameSeven MCP server.
 Package mcp exposes the FrameSeven MCP server.
report
Package report defines the scan result structure and renders CLI v1 reports.
 Package report defines the scan result structure and renders CLI v1 reports.
tools/v1/access
Package access tests broken access control: sensitive endpoints reachable without authentication, and IDOR by enumerating numeric identifiers.
 Package access tests broken access control: sensitive endpoints reachable without authentication, and IDOR by enumerating numeric identifiers.
tools/v1/auth
Package auth implements browser-based authentication capture.
 Package auth implements browser-based authentication capture.
tools/v1/auth_test
Package authtest checks authentication weaknesses: default credentials on login endpoints, missing account lockout, and JWTs signed with no algorithm or a weak, guessable secret.
 Package authtest checks authentication weaknesses: default credentials on login endpoints, missing account lockout, and JWTs signed with no algorithm or a weak, guessable secret.
tools/v1/bannergrab
Package bannergrab checks lightweight service banners for selected TCP services.
 Package bannergrab checks lightweight service banners for selected TCP services.
tools/v1/cmdi
Package cmdi tests OS command injection: it injects time-based payloads into command-like parameters and confirms a hit when the response is delayed, then escalates with output-based payloads to read command output and prove RCE.
 Package cmdi tests OS command injection: it injects time-based payloads into command-like parameters and confirms a hit when the response is delayed, then escalates with output-based payloads to read command output and prove RCE.
tools/v1/content
Package content discovers common web content paths.
 Package content discovers common web content paths.
tools/v1/crawler
Package crawler expands endpoint discovery by visiting already discovered same-origin pages and extracting additional links and form actions.
 Package crawler expands endpoint discovery by visiting already discovered same-origin pages and extracting additional links and form actions.
tools/v1/external
Package external runs external security binaries (such as Nmap and sqlmap) for Framework v1 in a fail-safe way: a missing binary, a non-zero exit, a timeout, or unparseable output is always turned into a finding instead of an error that could block the rest of the scan.
 Package external runs external security binaries (such as Nmap and sqlmap) for Framework v1 in a fail-safe way: a missing binary, a non-zero exit, a timeout, or unparseable output is always turned into a finding instead of an error that could block the rest of the scan.
tools/v1/external/nmap
Package nmap runs Nmap for Framework v1 and maps its results into findings.
 Package nmap runs Nmap for Framework v1 and maps its results into findings.
tools/v1/external/sqlmap
Package sqlmap runs sqlmap for Framework v1 and maps its result into a finding.
 Package sqlmap runs sqlmap for Framework v1 and maps its result into a finding.
tools/v1/lfi
Package lfi tests local file inclusion and path traversal: it injects traversal and PHP stream-wrapper payloads into parameters that look like file paths and confirms a hit when local file contents come back.
 Package lfi tests local file inclusion and path traversal: it injects traversal and PHP stream-wrapper payloads into parameters that look like file paths and confirms a hit when local file contents come back.
tools/v1/misconfig
Package misconfig checks for security misconfiguration: missing security headers, dangerous HTTP methods, permissive CORS and weak TLS.
 Package misconfig checks for security misconfiguration: missing security headers, dangerous HTTP methods, permissive CORS and weak TLS.
tools/v1/ports
Package ports performs light TCP checks against common web-facing ports.
 Package ports performs light TCP checks against common web-facing ports.
tools/v1/ratelimit
Package ratelimit measures whether the target throttles repeated requests by firing a burst and observing status-code and latency variation.
 Package ratelimit measures whether the target throttles repeated requests by firing a burst and observing status-code and latency variation.
tools/v1/recon
Package recon maps the attack surface of a target: DNS, response headers, technologies in use, sensitive files, and reachable endpoints/parameters.
 Package recon maps the attack surface of a target: DNS, response headers, technologies in use, sensitive files, and reachable endpoints/parameters.
tools/v1/redirect
Package redirect tests open redirects: it injects external destinations into redirect-like parameters and confirms a hit when the response redirects off the original origin via the Location header or a meta-refresh tag.
 Package redirect tests open redirects: it injects external destinations into redirect-like parameters and confirms a hit when the response redirects off the original origin via the Location header or a meta-refresh tag.
tools/v1/scanner
Package scanner orchestrates a full scan: it maps the surface with recon and then runs every test and enrichment tool against it, returning a report.
 Package scanner orchestrates a full scan: it maps the surface with recon and then runs every test and enrichment tool against it, returning a report.
tools/v1/sqli
Package sqli detects SQL injection (boolean-based) and, when a parameter is injectable, extracts real data with UNION-based payloads: DBMS, current database, current user, tables, columns and credential rows.
 Package sqli detects SQL injection (boolean-based) and, when a parameter is injectable, extracts real data with UNION-based payloads: DBMS, current database, current user, tables, columns and credential rows.
tools/v1/ssrf
Package ssrf tests server-side request forgery: it injects internal and cloud-metadata URLs into parameters that look like URLs and confirms a hit when the server returns metadata-service content.
 Package ssrf tests server-side request forgery: it injects internal and cloud-metadata URLs into parameters that look like URLs and confirms a hit when the server returns metadata-service content.
tools/v1/ssti
Package ssti tests server-side template injection: it injects math expressions that template engines evaluate, confirms a hit when the evaluated result comes back, fingerprints the engine, and attempts engine-specific RCE.
 Package ssti tests server-side template injection: it injects math expressions that template engines evaluate, confirms a hit when the evaluated result comes back, fingerprints the engine, and attempts engine-specific RCE.
tools/v1/subdomain
Package subdomain resolves a small seed list of common subdomain names.
 Package subdomain resolves a small seed list of common subdomain names.
tools/v1/xss
Package xss tests cross-site scripting: it injects marked payloads into discovered parameters and confirms reflected XSS when the payload comes back unencoded, stored XSS when a POSTed payload persists across a later GET, and flags DOM XSS sinks in discovered JavaScript files.
 Package xss tests cross-site scripting: it injects marked payloads into discovered parameters and confirms reflected XSS when the payload comes back unencoded, stored XSS when a POSTed payload persists across a later GET, and flags DOM XSS sinks in discovered JavaScript files.
tools/v1/xxe
Package xxe tests XML external entity and XML injection flaws: it posts XML documents that declare external entities pointing at local files and the cloud metadata endpoint, and confirms a hit when the entity content is reflected back.
 Package xxe tests XML external entity and XML injection flaws: it posts XML documents that declare external entities pointing at local files and the cloud metadata endpoint, and confirms a hit when the entity content is reflected back.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.