kmcp 0.1.5.dev0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (84) hide show
  1. kali_mcp/__init__.py +3 -0
  2. kali_mcp/__main__.py +28 -0
  3. kali_mcp/_version.py +24 -0
  4. kali_mcp/cli.py +169 -0
  5. kali_mcp/config.py +95 -0
  6. kali_mcp/db/__init__.py +1 -0
  7. kali_mcp/db/manager.py +248 -0
  8. kali_mcp/execution.py +439 -0
  9. kali_mcp/logging_utils.py +74 -0
  10. kali_mcp/models.py +51 -0
  11. kali_mcp/monitor/__init__.py +105 -0
  12. kali_mcp/monitor/sessions.py +70 -0
  13. kali_mcp/monitor/sse_client.py +87 -0
  14. kali_mcp/monitor/tui.py +364 -0
  15. kali_mcp/notifications.py +130 -0
  16. kali_mcp/prompts.py +184 -0
  17. kali_mcp/registry.py +33 -0
  18. kali_mcp/resources.py +263 -0
  19. kali_mcp/responses.py +39 -0
  20. kali_mcp/security.py +15 -0
  21. kali_mcp/server.py +535 -0
  22. kali_mcp/tools/__init__.py +125 -0
  23. kali_mcp/tools/amass.py +83 -0
  24. kali_mcp/tools/arjun.py +86 -0
  25. kali_mcp/tools/base.py +100 -0
  26. kali_mcp/tools/bettercap.py +99 -0
  27. kali_mcp/tools/bloodhound.py +68 -0
  28. kali_mcp/tools/commix.py +73 -0
  29. kali_mcp/tools/crackmapexec.py +100 -0
  30. kali_mcp/tools/dirb.py +75 -0
  31. kali_mcp/tools/dursgo.py +156 -0
  32. kali_mcp/tools/enum4linux.py +59 -0
  33. kali_mcp/tools/farsight.py +127 -0
  34. kali_mcp/tools/ffuf.py +85 -0
  35. kali_mcp/tools/file_download.py +119 -0
  36. kali_mcp/tools/file_read.py +144 -0
  37. kali_mcp/tools/file_write.py +141 -0
  38. kali_mcp/tools/flowlyt.py +88 -0
  39. kali_mcp/tools/generic_command.py +95 -0
  40. kali_mcp/tools/gobuster.py +84 -0
  41. kali_mcp/tools/hashcat.py +101 -0
  42. kali_mcp/tools/httpx.py +85 -0
  43. kali_mcp/tools/hydra.py +99 -0
  44. kali_mcp/tools/john.py +100 -0
  45. kali_mcp/tools/katana.py +81 -0
  46. kali_mcp/tools/masscan.py +85 -0
  47. kali_mcp/tools/medusa.py +102 -0
  48. kali_mcp/tools/msfconsole.py +59 -0
  49. kali_mcp/tools/naabu.py +100 -0
  50. kali_mcp/tools/netexec.py +86 -0
  51. kali_mcp/tools/nmap.py +94 -0
  52. kali_mcp/tools/normalization.py +18 -0
  53. kali_mcp/tools/nuclei.py +87 -0
  54. kali_mcp/tools/parallel_execute.py +246 -0
  55. kali_mcp/tools/persist.py +436 -0
  56. kali_mcp/tools/playbook_ad.py +99 -0
  57. kali_mcp/tools/playbook_engine.py +142 -0
  58. kali_mcp/tools/playbook_engine_tool.py +72 -0
  59. kali_mcp/tools/playbook_recon.py +115 -0
  60. kali_mcp/tools/playbook_tools.py +125 -0
  61. kali_mcp/tools/playbook_webapp.py +105 -0
  62. kali_mcp/tools/python_command.py +100 -0
  63. kali_mcp/tools/responder.py +85 -0
  64. kali_mcp/tools/searchsploit.py +123 -0
  65. kali_mcp/tools/spiderfoot.py +75 -0
  66. kali_mcp/tools/sqlmap.py +73 -0
  67. kali_mcp/tools/subfinder.py +69 -0
  68. kali_mcp/tools/theharvester.py +80 -0
  69. kali_mcp/tools/vault_tool.py +489 -0
  70. kali_mcp/tools/wfuzz.py +87 -0
  71. kali_mcp/tools/whatweb.py +82 -0
  72. kali_mcp/tools/wpscan.py +76 -0
  73. kali_mcp/tools/zap.py +79 -0
  74. kali_mcp/tools/zighound.py +139 -0
  75. kali_mcp/tools/zizmor.py +98 -0
  76. kali_mcp/utils/__init__.py +0 -0
  77. kali_mcp/utils/process.py +36 -0
  78. kali_mcp/utils/vault.py +471 -0
  79. kali_mcp/validation.py +82 -0
  80. kmcp-0.1.5.dev0.dist-info/METADATA +251 -0
  81. kmcp-0.1.5.dev0.dist-info/RECORD +84 -0
  82. kmcp-0.1.5.dev0.dist-info/WHEEL +5 -0
  83. kmcp-0.1.5.dev0.dist-info/entry_points.txt +4 -0
  84. kmcp-0.1.5.dev0.dist-info/top_level.txt +1 -0
@@ -0,0 +1,156 @@
1
+ """DursGo web application security scanner tool."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import logging
6
+ import shlex
7
+ from typing import Any
8
+
9
+ from kali_mcp.execution import engine
10
+ from kali_mcp.models import ToolError
11
+ from kali_mcp.responses import error_response, success_response
12
+ from kali_mcp.tools.base import BaseTool
13
+
14
+ logger = logging.getLogger("kali_mcp.tools")
15
+
16
+
17
+ class DursgoTool(BaseTool):
18
+ @property
19
+ def name(self) -> str:
20
+ return "dursgo"
21
+
22
+ @property
23
+ def description(self) -> str:
24
+ return (
25
+ "Run DursGo web application security scanner. "
26
+ "Supports XSS, SQLi, LFI, SSRF, IDOR, CSRF, command injection, SSTI, "
27
+ "CORS, file upload, BOLA, mass assignment, GraphQL, DOM XSS, and more."
28
+ )
29
+
30
+ @property
31
+ def default_timeout(self) -> int:
32
+ return 900
33
+
34
+ def input_schema(self) -> dict[str, Any]:
35
+ return {
36
+ "type": "object",
37
+ "properties": {
38
+ "target": {
39
+ "type": "string",
40
+ "description": "Target URL to scan (e.g. 'http://example.com')",
41
+ },
42
+ "scanners": {
43
+ "type": "string",
44
+ "description": (
45
+ "Comma-separated scanners: xss,sqli,lfi,openredirect,ssrf,exposed,"
46
+ "idor,csrf,cmdinjection,ssti,securityheaders,cors,fileupload,"
47
+ "bola,massassignment,graphql,blindssrf,domxss,subdomain. "
48
+ "Use 'all' for all scanners, 'none' for crawling only."
49
+ ),
50
+ "default": "all",
51
+ },
52
+ "concurrency": {
53
+ "type": "integer",
54
+ "description": "Number of concurrent workers (default 0 = auto)",
55
+ "default": 0,
56
+ },
57
+ "depth": {
58
+ "type": "integer",
59
+ "description": "Maximum crawling depth (default 0 = unlimited)",
60
+ "default": 0,
61
+ },
62
+ "delay": {
63
+ "type": "integer",
64
+ "description": "Delay between requests in milliseconds",
65
+ },
66
+ "retries": {
67
+ "type": "integer",
68
+ "description": "Maximum retries for failed requests",
69
+ },
70
+ "oast": {
71
+ "type": "boolean",
72
+ "description": "Enable OAST for blind vulnerabilities (Blind SSRF, Blind CMDi)",
73
+ },
74
+ "render_js": {
75
+ "type": "boolean",
76
+ "description": "Enable JS rendering via headless browser (required for domxss)",
77
+ },
78
+ "enrich": {
79
+ "type": "boolean",
80
+ "description": "Enable vulnerability enrichment with CISA KEV data",
81
+ },
82
+ "enable_ai": {
83
+ "type": "boolean",
84
+ "description": "Enable AI-powered analysis for found vulnerabilities",
85
+ },
86
+ "output_json": {
87
+ "type": "string",
88
+ "description": "Path to save JSON report (e.g. 'report.json')",
89
+ },
90
+ "insecure": {
91
+ "type": "boolean",
92
+ "description": "Skip TLS certificate verification",
93
+ },
94
+ "extra_args": {
95
+ "type": "string",
96
+ "description": "Additional DursGo arguments not covered above",
97
+ },
98
+ "timeout": {
99
+ "type": "integer",
100
+ "description": "Timeout in seconds (default 900)",
101
+ "default": 900,
102
+ },
103
+ },
104
+ "required": ["target"],
105
+ }
106
+
107
+ def validate(self, arguments: dict[str, Any]) -> None:
108
+ pass
109
+
110
+ def build_command(self, arguments: dict[str, Any]) -> list[str]:
111
+ cmd = ["dursgo", "-u", arguments["target"]]
112
+
113
+ scanners = arguments.get("scanners", "all")
114
+ cmd.extend(["-s", scanners])
115
+
116
+ if arguments.get("concurrency"):
117
+ cmd.extend(["-c", str(arguments["concurrency"])])
118
+ if arguments.get("depth"):
119
+ cmd.extend(["-d", str(arguments["depth"])])
120
+ if arguments.get("delay"):
121
+ cmd.extend(["-delay", str(arguments["delay"])])
122
+ if arguments.get("retries"):
123
+ cmd.extend(["-r", str(arguments["retries"])])
124
+ if arguments.get("oast"):
125
+ cmd.append("-oast")
126
+ if arguments.get("render_js"):
127
+ cmd.append("-render-js")
128
+ if arguments.get("enrich"):
129
+ cmd.append("-enrich")
130
+ if arguments.get("enable_ai"):
131
+ cmd.append("--enable-ai")
132
+ if arguments.get("output_json"):
133
+ cmd.extend(["-output-json", arguments["output_json"]])
134
+ if arguments.get("insecure"):
135
+ cmd.append("-insecure")
136
+
137
+ extra = arguments.get("extra_args")
138
+ if extra:
139
+ cmd.extend(shlex.split(extra))
140
+
141
+ return cmd
142
+
143
+ async def execute(self, arguments: dict[str, Any]) -> dict[str, Any]:
144
+ try:
145
+ self.validate(arguments)
146
+ except ValueError as e:
147
+ return error_response(ToolError(error="Validation error", details=str(e)))
148
+ except Exception as e:
149
+ logger.exception("Tool %s failed", self.name)
150
+ return error_response(ToolError(error="Execution failed", details=str(e)))
151
+
152
+ timeout = arguments.get("timeout", self.default_timeout)
153
+ cmd = self.build_command(arguments)
154
+
155
+ result = await engine.execute(cmd, tool=self.name, timeout=timeout)
156
+ return success_response(result)
@@ -0,0 +1,59 @@
1
+ """Enum4linux SMB enumeration tool."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import shlex
6
+ from typing import Any
7
+
8
+ from kali_mcp.execution import engine
9
+ from kali_mcp.models import ToolError
10
+ from kali_mcp.responses import error_response, success_response
11
+ from kali_mcp.tools.base import BaseTool
12
+ from kali_mcp.validation import validate_ip, validate_required, validate_timeout
13
+
14
+
15
+ class Enum4linuxTool(BaseTool):
16
+ @property
17
+ def name(self) -> str:
18
+ return "enum4linux"
19
+
20
+ @property
21
+ def description(self) -> str:
22
+ return "Run enum4linux-ng for SMB/Samba enumeration."
23
+
24
+ def input_schema(self) -> dict[str, Any]:
25
+ return {
26
+ "type": "object",
27
+ "properties": {
28
+ "target": {"type": "string", "description": "Target IP address"},
29
+ "extra_args": {"type": "string", "description": "Additional arguments"},
30
+ "timeout": {"type": "integer", "default": 300},
31
+ },
32
+ "required": ["target"],
33
+ }
34
+
35
+ def validate(self, arguments: dict[str, Any]) -> None:
36
+ validate_required(arguments, "target")
37
+ validate_ip(arguments["target"])
38
+ if "timeout" in arguments:
39
+ validate_timeout(arguments["timeout"])
40
+
41
+ def build_command(self, arguments: dict[str, Any]) -> list[str]:
42
+ cmd = ["enum4linux", "-a", arguments["target"]]
43
+ extra = arguments.get("extra_args")
44
+ if extra:
45
+ cmd.extend(shlex.split(extra))
46
+ return cmd
47
+
48
+ async def execute(self, arguments: dict[str, Any]) -> dict[str, Any]:
49
+ try:
50
+ self.validate(arguments)
51
+ except ValueError as e:
52
+ return error_response(ToolError(error="Validation error", details=str(e)))
53
+ return success_response(
54
+ await engine.execute(
55
+ command=self.build_command(arguments),
56
+ tool=self.name,
57
+ timeout=arguments.get("timeout", self.default_timeout),
58
+ )
59
+ )
@@ -0,0 +1,127 @@
1
+ """Farsight domain intelligence and reconnaissance tool."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import logging
6
+ import uuid
7
+ from pathlib import Path
8
+ from typing import Any
9
+
10
+ from kali_mcp.execution import engine
11
+ from kali_mcp.models import ToolError
12
+ from kali_mcp.responses import error_response, success_response
13
+ from kali_mcp.tools.base import BaseTool
14
+ from kali_mcp.validation import validate_domain
15
+
16
+ logger = logging.getLogger("kali_mcp.tools")
17
+ from kali_mcp.config import config
18
+
19
+
20
+ class FarsightTool(BaseTool):
21
+ @property
22
+ def name(self) -> str:
23
+ return "farsight"
24
+
25
+ @property
26
+ def description(self) -> str:
27
+ return (
28
+ "Run Farsight domain intelligence scanner. "
29
+ "Performs recon, asset discovery, threat intel, typosquat detection, "
30
+ "and news monitoring against a target domain."
31
+ )
32
+
33
+ @property
34
+ def default_timeout(self) -> int:
35
+ return 120
36
+
37
+ def input_schema(self) -> dict[str, Any]:
38
+ return {
39
+ "type": "object",
40
+ "properties": {
41
+ "domain": {
42
+ "type": "string",
43
+ "description": "Target domain to scan (e.g. 'example.com')",
44
+ },
45
+ "depth": {
46
+ "type": "integer",
47
+ "description": "Scan depth 1-3 (default 1)",
48
+ "default": 1,
49
+ },
50
+ "all_modules": {
51
+ "type": "boolean",
52
+ "description": "Enable all scan modules (default false)",
53
+ "default": False,
54
+ },
55
+ "timeout": {
56
+ "type": "integer",
57
+ "description": "Timeout in seconds (default 120)",
58
+ "default": 120,
59
+ },
60
+ },
61
+ "required": ["domain"],
62
+ }
63
+
64
+ def validate(self, arguments: dict[str, Any]) -> None:
65
+ domain = arguments.get("domain")
66
+ if not isinstance(domain, str) or not domain.strip():
67
+ raise ValueError("Missing required parameter: domain")
68
+ validate_domain(domain.strip())
69
+ depth = arguments.get("depth", 1)
70
+ try:
71
+ depth = int(depth)
72
+ except (ValueError, TypeError):
73
+ raise ValueError(f"Depth must be an integer, got {depth!r}")
74
+ if depth < 1 or depth > 3:
75
+ raise ValueError(f"Depth must be between 1 and 3, got {depth}")
76
+
77
+ def build_command(self, arguments: dict[str, Any]) -> list[str]:
78
+ cmd, _report_path = self._build_full(arguments)
79
+ return cmd
80
+
81
+ def _build_full(self, arguments: dict[str, Any]) -> tuple[list[str], Path]:
82
+ report_path = config.artifact_dir / f"farsight_{uuid.uuid4().hex[:8]}.md"
83
+ cmd = ["farsight", "scan", arguments["domain"]]
84
+ cmd.extend(["-o", str(report_path)])
85
+ depth = arguments.get("depth", 1)
86
+ cmd.extend(["-d", str(depth)])
87
+ if arguments.get("all_modules"):
88
+ cmd.append("--all")
89
+ return cmd, report_path
90
+
91
+ async def execute(self, arguments: dict[str, Any]) -> dict[str, Any]:
92
+ try:
93
+ self.validate(arguments)
94
+ except ValueError as e:
95
+ return error_response(ToolError(error="Validation error", details=str(e)))
96
+ except Exception as e:
97
+ logger.exception("Tool %s failed", self.name)
98
+ return error_response(ToolError(error="Execution failed", details=str(e)))
99
+
100
+ timeout = arguments.get("timeout", self.default_timeout)
101
+ cmd, report_path = self._build_full(arguments)
102
+
103
+ result = await engine.execute(cmd, tool=self.name, timeout=timeout)
104
+
105
+ # Read the report file back with integrity check
106
+ if report_path.exists():
107
+ try:
108
+ file_size = report_path.stat().st_size
109
+ if file_size == 0:
110
+ result.stderr = "Report file is empty"
111
+ result.success = False
112
+ else:
113
+ report_content = report_path.read_text(encoding="utf-8")
114
+ if not report_content.strip():
115
+ result.stderr = "Report file contains no content"
116
+ result.success = False
117
+ else:
118
+ result.stdout = f"=== Report: {report_path.name} ({file_size} bytes) ===\n\n{report_content}"
119
+ except (OSError, UnicodeDecodeError) as e:
120
+ result.stderr = f"Failed to read report: {e}"
121
+ result.success = False
122
+ else:
123
+ if result.success:
124
+ result.stderr = "Report file not created by farsight"
125
+ result.success = False
126
+
127
+ return success_response(result)
kali_mcp/tools/ffuf.py ADDED
@@ -0,0 +1,85 @@
1
+ """FFUF web fuzzer tool."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import shlex
6
+ from typing import Any
7
+
8
+ from kali_mcp.execution import engine
9
+ from kali_mcp.models import ToolError
10
+ from kali_mcp.responses import error_response, success_response
11
+ from kali_mcp.tools.base import BaseTool
12
+ from kali_mcp.validation import validate_required, validate_timeout
13
+
14
+
15
+ class FfufTool(BaseTool):
16
+ @property
17
+ def name(self) -> str:
18
+ return "ffuf"
19
+
20
+ @property
21
+ def description(self) -> str:
22
+ return (
23
+ "Run ffuf for web fuzzing — directory discovery, parameter fuzzing, vhost enumeration."
24
+ )
25
+
26
+ @property
27
+ def default_timeout(self) -> int:
28
+ return 600
29
+
30
+ def input_schema(self) -> dict[str, Any]:
31
+ return {
32
+ "type": "object",
33
+ "properties": {
34
+ "target": {
35
+ "type": "string",
36
+ "description": "Target URL with FUZZ keyword (e.g. 'https://target.com/FUZZ')",
37
+ },
38
+ "wordlist": {"type": "string", "description": "Path to wordlist file"},
39
+ "filter": {
40
+ "type": "string",
41
+ "description": "Filter flags (e.g. '-fc 404 -fs 0')",
42
+ },
43
+ "extra_args": {
44
+ "type": "string",
45
+ "description": "Additional ffuf arguments",
46
+ },
47
+ "timeout": {
48
+ "type": "integer",
49
+ "description": "Timeout in seconds (default 600)",
50
+ "default": 600,
51
+ },
52
+ },
53
+ "required": ["target", "wordlist"],
54
+ }
55
+
56
+ def validate(self, arguments: dict[str, Any]) -> None:
57
+ validate_required(arguments, "target", "wordlist")
58
+ if "timeout" in arguments:
59
+ validate_timeout(arguments["timeout"])
60
+
61
+ def build_command(self, arguments: dict[str, Any]) -> list[str]:
62
+ target = arguments["target"]
63
+ if not target.startswith(("http://", "https://")):
64
+ target = f"http://{target}"
65
+ cmd = ["ffuf", "-u", target, "-w", arguments["wordlist"]]
66
+ filter_val = arguments.get("filter")
67
+ if filter_val:
68
+ cmd.extend(shlex.split(filter_val))
69
+ extra = arguments.get("extra_args")
70
+ if extra:
71
+ cmd.extend(shlex.split(extra))
72
+ return cmd
73
+
74
+ async def execute(self, arguments: dict[str, Any]) -> dict[str, Any]:
75
+ try:
76
+ self.validate(arguments)
77
+ except ValueError as e:
78
+ return error_response(ToolError(error="Validation error", details=str(e)))
79
+ return success_response(
80
+ await engine.execute(
81
+ command=self.build_command(arguments),
82
+ tool=self.name,
83
+ timeout=arguments.get("timeout", self.default_timeout),
84
+ )
85
+ )
@@ -0,0 +1,119 @@
1
+ """File download tool — generate download links for server-to-agent file transfers."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import logging
6
+ import os
7
+ import shlex
8
+ import socket
9
+ from typing import Any
10
+
11
+ from kali_mcp.models import ExecutionResult, ToolError, utc_now_iso
12
+ from kali_mcp.responses import error_response, success_response
13
+ from kali_mcp.tools.base import BaseTool
14
+ from kali_mcp.validation import validate_required
15
+
16
+ logger = logging.getLogger("kali_mcp.tools")
17
+
18
+
19
+ def _get_download_host() -> str:
20
+ """Resolve the externally-reachable host for download URLs."""
21
+ from kali_mcp.config import config
22
+
23
+ host = config.host
24
+ if host and host not in ("0.0.0.0", "::"):
25
+ return host
26
+ try:
27
+ s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
28
+ s.connect(("10.255.255.255", 1))
29
+ ip = s.getsockname()[0]
30
+ s.close()
31
+ return ip
32
+ except Exception: # noqa: BLE001
33
+ return "localhost"
34
+
35
+
36
+ class FileDownloadTool(BaseTool):
37
+ @property
38
+ def name(self) -> str:
39
+ return "file_download"
40
+
41
+ @property
42
+ def description(self) -> str:
43
+ return (
44
+ "Generate a download link for a file on the Kali server. "
45
+ "Returns a curl command the agent can run to save the file locally."
46
+ )
47
+
48
+ @property
49
+ def default_timeout(self) -> int:
50
+ return 60
51
+
52
+ def input_schema(self) -> dict[str, Any]:
53
+ return {
54
+ "type": "object",
55
+ "properties": {
56
+ "server_path": {
57
+ "type": "string",
58
+ "description": "Absolute path to the file on the Kali server",
59
+ },
60
+ "local_path": {
61
+ "type": "string",
62
+ "description": "Local path to save the file (default: basename of server_path)",
63
+ "default": "",
64
+ },
65
+ },
66
+ "required": ["server_path"],
67
+ }
68
+
69
+ def validate(self, arguments: dict[str, Any]) -> None:
70
+ validate_required(arguments, "server_path")
71
+ path = arguments["server_path"]
72
+ if not isinstance(path, str) or not path.strip():
73
+ raise ValueError("server_path must be a non-empty string")
74
+ if not os.path.isfile(path):
75
+ raise ValueError(f"File not found: {path}")
76
+
77
+ def build_command(self, arguments: dict[str, Any]) -> list[str]:
78
+ return ["file_download", arguments.get("server_path", "")]
79
+
80
+ async def execute(self, arguments: dict[str, Any]) -> dict[str, Any]:
81
+ try:
82
+ self.validate(arguments)
83
+ except ValueError as e:
84
+ return error_response(ToolError(error="Validation error", details=str(e)))
85
+
86
+ server_path = os.path.realpath(arguments["server_path"])
87
+ local_path = arguments.get("local_path") or os.path.basename(server_path)
88
+ file_size = os.path.getsize(server_path)
89
+
90
+ from kali_mcp.config import config
91
+
92
+ host = _get_download_host()
93
+ port = config.port
94
+ download_url = f"http://{host}:{port}/download?path={shlex.quote(server_path)}"
95
+
96
+ curl_cmd = f"curl -sS -o {shlex.quote(local_path)} {shlex.quote(download_url)}"
97
+
98
+ if config.api_token:
99
+ curl_cmd += f' -H "Authorization: Bearer {config.api_token}"'
100
+
101
+ stdout = (
102
+ f"Download ready: {server_path} ({file_size:,} bytes)\n\n"
103
+ f"Run this command to save to {local_path}:\n{curl_cmd}"
104
+ )
105
+
106
+ result = ExecutionResult(
107
+ tool=self.name,
108
+ command=f"file_download {server_path}",
109
+ stdout=stdout,
110
+ stderr="",
111
+ exit_code=0,
112
+ success=True,
113
+ timed_out=False,
114
+ duration=0.0,
115
+ start_time=utc_now_iso(),
116
+ end_time=utc_now_iso(),
117
+ )
118
+
119
+ return success_response(result)
@@ -0,0 +1,144 @@
1
+ """File read tool — read files from the Kali machine."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import json
6
+ import os
7
+
8
+ # Allowed directories for file reads (configurable via env)
9
+ import os as _os
10
+ from typing import Any
11
+
12
+ from kali_mcp.models import ExecutionResult, ToolError, utc_now_iso
13
+ from kali_mcp.responses import error_response, success_response
14
+ from kali_mcp.tools.base import BaseTool
15
+ from kali_mcp.validation import validate_required
16
+
17
+ _ALLOWED_DIRS_ENV = _os.getenv("MCP_ALLOWED_READ_DIRS", "")
18
+ ALLOWED_READ_DIRS = [d.strip() for d in _ALLOWED_DIRS_ENV.split(",") if d.strip()]
19
+
20
+
21
+ class FileReadTool(BaseTool):
22
+ @property
23
+ def name(self) -> str:
24
+ return "file_read"
25
+
26
+ @property
27
+ def description(self) -> str:
28
+ return (
29
+ "Read a file from the Kali machine. Returns the file content, "
30
+ "size, and metadata. Use for reading scan results, configs, "
31
+ "wordlists, reports, logs, or any file on the system."
32
+ )
33
+
34
+ @property
35
+ def default_timeout(self) -> int:
36
+ return 30
37
+
38
+ def input_schema(self) -> dict[str, Any]:
39
+ return {
40
+ "type": "object",
41
+ "properties": {
42
+ "path": {
43
+ "type": "string",
44
+ "description": "Absolute path to the file to read",
45
+ },
46
+ "max_bytes": {
47
+ "type": "integer",
48
+ "description": "Maximum bytes to read (default 1MB). Large files are truncated.",
49
+ "default": 1048576,
50
+ },
51
+ "offset": {
52
+ "type": "integer",
53
+ "description": "Byte offset to start reading from (default 0). Useful for large files.",
54
+ "default": 0,
55
+ },
56
+ },
57
+ "required": ["path"],
58
+ }
59
+
60
+ def validate(self, arguments: dict[str, Any]) -> None:
61
+ validate_required(arguments, "path")
62
+ path = arguments["path"]
63
+ if not isinstance(path, str) or not path.strip():
64
+ raise ValueError("Path must be a non-empty string")
65
+ # Path containment check (skip if no dirs configured = unrestricted)
66
+ if ALLOWED_READ_DIRS:
67
+ resolved = os.path.realpath(path)
68
+ if not any(resolved.startswith(d + "/") or resolved == d for d in ALLOWED_READ_DIRS):
69
+ raise ValueError(
70
+ f"Path not in allowed directories: {resolved}. "
71
+ f"Allowed: {', '.join(ALLOWED_READ_DIRS)}"
72
+ )
73
+
74
+ def build_command(self, arguments: dict[str, Any]) -> list[str]:
75
+ return ["cat", arguments["path"]]
76
+
77
+ async def execute(self, arguments: dict[str, Any]) -> dict[str, Any]:
78
+ try:
79
+ self.validate(arguments)
80
+ except ValueError as e:
81
+ return error_response(ToolError(error="Validation error", details=str(e)))
82
+
83
+ path = arguments["path"]
84
+ max_bytes = arguments.get("max_bytes", 1048576)
85
+ offset = arguments.get("offset", 0)
86
+
87
+ if not os.path.isfile(path):
88
+ return error_response(
89
+ ToolError(
90
+ error="File not found",
91
+ details=f"No such file: {path}",
92
+ )
93
+ )
94
+
95
+ try:
96
+ file_size = os.path.getsize(path)
97
+
98
+ with open(path, "r", errors="replace") as f: # noqa: ASYNC230
99
+ if offset > 0:
100
+ f.seek(offset)
101
+ content = f.read(max_bytes)
102
+
103
+ truncated = (offset + len(content.encode("utf-8"))) < file_size
104
+
105
+ result = {
106
+ "tool": self.name,
107
+ "path": path,
108
+ "file_size": file_size,
109
+ "offset": offset,
110
+ "bytes_read": len(content.encode("utf-8")),
111
+ "truncated": truncated,
112
+ "content": content,
113
+ }
114
+
115
+ result = ExecutionResult(
116
+ tool=self.name,
117
+ command=f"cat {path}",
118
+ stdout=json.dumps(
119
+ {
120
+ "path": path,
121
+ "file_size": file_size,
122
+ "offset": offset,
123
+ "bytes_read": len(content.encode("utf-8")),
124
+ "truncated": truncated,
125
+ "content": content,
126
+ }
127
+ ),
128
+ stderr="",
129
+ exit_code=0,
130
+ success=True,
131
+ timed_out=False,
132
+ duration=0.0,
133
+ start_time=utc_now_iso(),
134
+ end_time=utc_now_iso(),
135
+ )
136
+
137
+ return success_response(result)
138
+ except Exception as e: # noqa: BLE001
139
+ return error_response(
140
+ ToolError(
141
+ error="Read failed",
142
+ details=str(e),
143
+ )
144
+ )