souleyez 2.43.29__py3-none-any.whl → 2.43.34__py3-none-any.whl

souleyez/plugins/vnc_access.py

@@ -25,10 +25,10 @@ HELP = {
         "- VNC gives full mouse/keyboard control\n"
         "- Some viewers support file transfer\n"
     ),
-    "usage": "souleyez jobs enqueue vnc_access <target> --args \"--password <pass>\"",
+    "usage": 'souleyez jobs enqueue vnc_access <target> --args "--password <pass>"',
     "examples": [
-        "souleyez jobs enqueue vnc_access 192.168.1.100 --args \"--password secret\"",
-        "souleyez jobs enqueue vnc_access 192.168.1.100:5901 --args \"--password secret\"",
+        'souleyez jobs enqueue vnc_access 192.168.1.100 --args "--password secret"',
+        'souleyez jobs enqueue vnc_access 192.168.1.100:5901 --args "--password secret"',
     ],
     "flags": [
         ["--password PASS", "VNC password"],
@@ -37,7 +37,87 @@ HELP = {
     ],
     "presets": [
         {"name": "Connect", "args": [], "desc": "Interactive VNC session"},
-        {"name": "Screenshot", "args": ["--screenshot"], "desc": "Capture screenshot only"},
+        {
+            "name": "Screenshot",
+            "args": ["--screenshot"],
+            "desc": "Capture screenshot only",
+        },
+    ],
+    "help_sections": [
+        {
+            "title": "What is VNC Access?",
+            "color": "cyan",
+            "content": [
+                (
+                    "Overview",
+                    [
+                        "Connects to VNC servers after obtaining credentials",
+                        "Provides full graphical remote desktop access",
+                        "Can take screenshots for headless/automated operation",
+                    ],
+                ),
+                (
+                    "When to Use",
+                    [
+                        "After VNC brute force discovers valid password",
+                        "When you need GUI access (no command line available)",
+                        "For accessing macOS Screen Sharing (port 5900)",
+                        "To capture screenshots for documentation/evidence",
+                    ],
+                ),
+            ],
+        },
+        {
+            "title": "Usage & Examples",
+            "color": "green",
+            "content": [
+                (
+                    "Interactive Session",
+                    [
+                        'souleyez jobs enqueue vnc_access 192.168.1.100 --args "--password secret"',
+                        "  → Opens VNC viewer for interactive control",
+                    ],
+                ),
+                (
+                    "Custom Port",
+                    [
+                        'souleyez jobs enqueue vnc_access 192.168.1.100:5901 --args "--password secret"',
+                        "  → Connects to VNC on non-standard port",
+                    ],
+                ),
+                (
+                    "Screenshot Mode",
+                    [
+                        'souleyez jobs enqueue vnc_access 192.168.1.100 --args "--password secret --screenshot"',
+                        "  → Captures screenshot without interactive session",
+                    ],
+                ),
+            ],
+        },
+        {
+            "title": "VNC Ports & Tips",
+            "color": "yellow",
+            "content": [
+                (
+                    "Common VNC Ports",
+                    [
+                        "5900 - Standard VNC / macOS Screen Sharing",
+                        "5901 - VNC display :1",
+                        "5902 - VNC display :2",
+                        "5800 - Java VNC (web-based)",
+                    ],
+                ),
+                (
+                    "Access Capabilities",
+                    [
+                        "Full mouse and keyboard control",
+                        "View running applications and files",
+                        "Some viewers support file transfer",
+                        "Can be used for credential harvesting (watch user type)",
+                    ],
+                ),
+            ],
+        },
     ],
 }
 
@@ -50,54 +130,59 @@ class VNCAccessPlugin(PluginBase):
 
     def check_tool_available(self) -> tuple:
         """Check if a VNC viewer is available."""
-        viewers = ['vncviewer', 'vinagre', 'remmina', 'xtightvncviewer']
+        viewers = ["vncviewer", "vinagre", "remmina", "xtightvncviewer"]
         for viewer in viewers:
             if shutil.which(viewer):
                 return True, None
-        return False, "VNC viewer not found. Install with: sudo apt install tigervnc-viewer"
+        return (
+            False,
+            "VNC viewer not found. Install with: sudo apt install tigervnc-viewer",
+        )
 
     def _find_viewer(self) -> str:
         """Find an available VNC viewer."""
-        viewers = ['vncviewer', 'xtightvncviewer', 'vinagre', 'remmina']
+        viewers = ["vncviewer", "xtightvncviewer", "vinagre", "remmina"]
         for viewer in viewers:
             if shutil.which(viewer):
                 return viewer
-        return 'vncviewer'
+        return "vncviewer"
 
-    def build_command(self, target: str, args: List[str] = None, label: str = "", log_path: str = None):
+    def build_command(
+        self, target: str, args: List[str] = None, label: str = "", log_path: str = None
+    ):
         """Build VNC viewer command."""
         args = args or []
 
         try:
             # Allow target:port format
-            if ':' in target and target.count(':') == 1:
-                host, port = target.rsplit(':', 1)
+            if ":" in target and target.count(":") == 1:
+                host, port = target.rsplit(":", 1)
                 try:
                     int(port)
                     target = host
-                    args = ['--port', port] + args
+                    args = ["--port", port] + args
                 except ValueError:
                     pass
             target = validate_target(target)
         except ValidationError as e:
             if log_path:
-                with open(log_path, 'w') as f:
+                with open(log_path, "w") as f:
                     f.write(f"ERROR: Invalid target: {e}\n")
             return None
 
         password = None
-        port = '5900'
+        port = "5900"
         screenshot = False
 
         i = 0
         while i < len(args):
-            if args[i] == '--password' and i + 1 < len(args):
+            if args[i] == "--password" and i + 1 < len(args):
                 password = args[i + 1]
                 i += 2
-            elif args[i] == '--port' and i + 1 < len(args):
+            elif args[i] == "--port" and i + 1 < len(args):
                 port = args[i + 1]
                 i += 2
-            elif args[i] == '--screenshot':
+            elif args[i] == "--screenshot":
                 screenshot = True
                 i += 1
             else:
@@ -107,54 +192,51 @@ class VNCAccessPlugin(PluginBase):
 
         if screenshot:
             # Use vncsnapshot if available, otherwise vncviewer in headless mode
-            if shutil.which('vncsnapshot'):
-                cmd = ['vncsnapshot', f'{target}:{port}', '/tmp/vnc_screenshot.jpg']
+            if shutil.which("vncsnapshot"):
+                cmd = ["vncsnapshot", f"{target}:{port}", "/tmp/vnc_screenshot.jpg"]
                 if password:
-                    cmd.extend(['-passwd', password])
+                    cmd.extend(["-passwd", password])
             else:
                 if log_path:
-                    with open(log_path, 'w') as f:
+                    with open(log_path, "w") as f:
                         f.write("# Screenshot mode requires vncsnapshot\n")
                         f.write("Install with: sudo apt install vncsnapshot\n")
                 return None
         else:
             # Interactive session
-            cmd = [viewer, f'{target}::{port}']
+            cmd = [viewer, f"{target}::{port}"]
             # vncviewer password handling varies by implementation
             # Most accept password via stdin or password file
 
         return {
-            'cmd': cmd,
-            'timeout': 30,  # Just connection timeout, session runs until user closes
-            'password': password
+            "cmd": cmd,
+            "timeout": 30,  # Just connection timeout, session runs until user closes
+            "password": password,
         }
 
-    def run(self, target: str, args: List[str] = None, label: str = "", log_path: str = None) -> int:
+    def run(
+        self, target: str, args: List[str] = None, label: str = "", log_path: str = None
+    ) -> int:
         """Execute VNC connection."""
         cmd_spec = self.build_command(target, args, label, log_path)
         if cmd_spec is None:
             return 1
 
-        cmd = cmd_spec['cmd']
-        password = cmd_spec.get('password')
+        cmd = cmd_spec["cmd"]
+        password = cmd_spec.get("password")
 
         if log_path:
-            with open(log_path, 'w') as f:
+            with open(log_path, "w") as f:
                 f.write(f"# VNC Access to {target}\n")
                 f.write(f"# Command: {' '.join(cmd)}\n")
                 f.write(f"# Started: {time.strftime('%Y-%m-%d %H:%M:%S')}\n\n")
 
         try:
             # For screenshot mode, capture output
-            if 'vncsnapshot' in cmd[0]:
-                result = subprocess.run(
-                    cmd,
-                    capture_output=True,
-                    text=True,
-                    timeout=30
-                )
+            if "vncsnapshot" in cmd[0]:
+                result = subprocess.run(cmd, capture_output=True, text=True, timeout=30)
                 if log_path:
-                    with open(log_path, 'a') as f:
+                    with open(log_path, "a") as f:
                         f.write(result.stdout)
                         if result.stderr:
                             f.write(f"\nStderr: {result.stderr}\n")
@@ -164,27 +246,32 @@ class VNCAccessPlugin(PluginBase):
             else:
                 # Interactive mode - just launch and return
                 if log_path:
-                    with open(log_path, 'a') as f:
+                    with open(log_path, "a") as f:
                         f.write("Launching VNC viewer...\n")
                         f.write("Note: Interactive session - check viewer window\n")
 
                 # Use Popen for non-blocking launch
-                subprocess.Popen(cmd, stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+                subprocess.Popen(
+                    cmd,
+                    stdin=subprocess.DEVNULL,
+                    stdout=subprocess.DEVNULL,
+                    stderr=subprocess.DEVNULL,
+                )
                 return 0
 
         except subprocess.TimeoutExpired:
             if log_path:
-                with open(log_path, 'a') as f:
+                with open(log_path, "a") as f:
                     f.write("\n\n# ERROR: Connection timed out\n")
             return 124
         except FileNotFoundError:
             if log_path:
-                with open(log_path, 'a') as f:
+                with open(log_path, "a") as f:
                     f.write("\n\n# ERROR: VNC viewer not found\n")
             return 127
         except Exception as e:
             if log_path:
-                with open(log_path, 'a') as f:
+                with open(log_path, "a") as f:
                     f.write(f"\n\n# ERROR: {e}\n")
             return 1
 

souleyez/plugins/vnc_brute.py

@@ -29,7 +29,7 @@ HELP = {
     "usage": "souleyez jobs enqueue vnc_brute <target>",
     "examples": [
         "souleyez jobs enqueue vnc_brute 192.168.1.100",
-        "souleyez jobs enqueue vnc_brute 192.168.1.100 --args \"--port 5901\"",
+        'souleyez jobs enqueue vnc_brute 192.168.1.100 --args "--port 5901"',
     ],
     "flags": [
         ["--port PORT", "VNC port (default: 5900)"],
@@ -38,6 +38,82 @@ HELP = {
         {"name": "Standard VNC", "args": [], "desc": "Port 5900"},
         {"name": "Display :1", "args": ["--port", "5901"], "desc": "Port 5901"},
     ],
+    "help_sections": [
+        {
+            "title": "What is VNC Brute Force?",
+            "color": "cyan",
+            "content": [
+                (
+                    "Overview",
+                    [
+                        "Brute forces VNC/Screen Sharing password authentication",
+                        "Uses Hydra with common VNC passwords",
+                        "Targets graphical remote access to systems",
+                    ],
+                ),
+                (
+                    "VNC Authentication Types",
+                    [
+                        "VNC-only password (separate from user accounts)",
+                        "macOS user credentials (Screen Sharing)",
+                        "No authentication (dangerous but common!)",
+                    ],
+                ),
+            ],
+        },
+        {
+            "title": "Usage & Examples",
+            "color": "green",
+            "content": [
+                (
+                    "Basic Usage",
+                    [
+                        "souleyez jobs enqueue vnc_brute 192.168.1.100",
+                        "  → Tests common VNC passwords on port 5900",
+                    ],
+                ),
+                (
+                    "Custom Port",
+                    [
+                        'souleyez jobs enqueue vnc_brute 192.168.1.100 --args "--port 5901"',
+                        "  → Tests VNC on display :1 (port 5901)",
+                    ],
+                ),
+            ],
+        },
+        {
+            "title": "Tips & Common Passwords",
+            "color": "yellow",
+            "content": [
+                (
+                    "Common VNC Passwords",
+                    [
+                        "password, vnc, 123456, admin",
+                        "Often same as login password",
+                        "Many systems use blank password (no auth!)",
+                        "8 character max on traditional VNC",
+                    ],
+                ),
+                (
+                    "VNC Ports to Check",
+                    [
+                        "5900 - Display :0 / macOS Screen Sharing",
+                        "5901 - Display :1",
+                        "5800 - Java VNC (browser-based)",
+                    ],
+                ),
+                (
+                    "After Success",
+                    [
+                        "Use vnc_access to connect interactively",
+                        "Full graphical desktop control",
+                        "Can view files, run programs, keylog",
+                        "Watch for open sessions with sensitive data",
+                    ],
+                ),
+            ],
+        },
+    ],
 }
 
 
@@ -49,18 +125,13 @@ class VNCBrutePlugin(PluginBase):
 
     def _get_wordlist_path(self, filename: str) -> str:
         """Get path to wordlist file."""
-        import os
-        locations = [
-            os.path.join(os.path.dirname(__file__), '..', 'data', 'wordlists', filename),
-            os.path.expanduser(f'~/.souleyez/wordlists/{filename}'),
-            f'/usr/share/seclists/Passwords/{filename}',
-        ]
-        for loc in locations:
-            if os.path.exists(loc):
-                return os.path.abspath(loc)
-        return filename
+        from souleyez.wordlists import resolve_wordlist_path
+
+        return resolve_wordlist_path(f"data/wordlists/{filename}")
 
-    def build_command(self, target: str, args: List[str] = None, label: str = "", log_path: str = None):
+    def build_command(
+        self, target: str, args: List[str] = None, label: str = "", log_path: str = None
+    ):
         """Build Hydra command for VNC brute force."""
         args = args or []
 
@@ -68,69 +139,69 @@ class VNCBrutePlugin(PluginBase):
             target = validate_target(target)
         except ValidationError as e:
             if log_path:
-                with open(log_path, 'w') as f:
+                with open(log_path, "w") as f:
                     f.write(f"ERROR: Invalid target: {e}\n")
             return None
 
-        port = '5900'
+        port = "5900"
         i = 0
         while i < len(args):
-            if args[i] == '--port' and i + 1 < len(args):
+            if args[i] == "--port" and i + 1 < len(args):
                 port = args[i + 1]
                 i += 2
             else:
                 i += 1
 
-        passwords = self._get_wordlist_path('vnc_passwords.txt')
+        passwords = self._get_wordlist_path("vnc_passwords.txt")
 
         cmd = [
-            'hydra',
-            '-P', passwords,
-            '-s', port,
-            '-t', '2',
-            '-w', '3',
-            '-vV',
-            '-f',
+            "hydra",
+            "-P",
+            passwords,
+            "-s",
+            port,
+            "-t",
+            "2",
+            "-w",
+            "3",
+            "-vV",
+            "-f",
             target,
-            'vnc'
+            "vnc",
         ]
 
-        return {
-            'cmd': cmd,
-            'timeout': 1800
-        }
+        return {"cmd": cmd, "timeout": 1800}
 
-    def run(self, target: str, args: List[str] = None, label: str = "", log_path: str = None) -> int:
+    def run(
+        self, target: str, args: List[str] = None, label: str = "", log_path: str = None
+    ) -> int:
         """Execute VNC brute force."""
         cmd_spec = self.build_command(target, args, label, log_path)
         if cmd_spec is None:
             return 1
 
-        cmd = cmd_spec['cmd']
+        cmd = cmd_spec["cmd"]
 
         if log_path:
-            with open(log_path, 'w') as f:
+            with open(log_path, "w") as f:
                 f.write(f"# VNC Brute Force on {target}\n")
                 f.write(f"# Command: {' '.join(cmd)}\n")
                 f.write(f"# Started: {time.strftime('%Y-%m-%d %H:%M:%S')}\n\n")
 
         try:
-            with open(log_path, 'a') as f:
+            with open(log_path, "a") as f:
                 result = subprocess.run(
-                    cmd,
-                    stdout=f,
-                    stderr=subprocess.STDOUT,
-                    timeout=cmd_spec['timeout']
+                    cmd, stdout=f, stderr=subprocess.STDOUT, timeout=cmd_spec["timeout"]
                 )
             return result.returncode
         except subprocess.TimeoutExpired:
             if log_path:
-                with open(log_path, 'a') as f:
+                with open(log_path, "a") as f:
                     f.write("\n\n# ERROR: Brute force timed out\n")
             return 124
         except Exception as e:
             if log_path:
-                with open(log_path, 'a') as f:
+                with open(log_path, "a") as f:
                     f.write(f"\n\n# ERROR: {e}\n")
             return 1