fix(security): remove pre-existing bandit HIGH findings and enable the HIGH gate (#2350)

Bandit ran warning-only, so 18 pre-existing HIGH-severity findings sat
unblocked in core paths (CLI, subprocess helpers, MCP stdio transport,
Lemonade launch). Before: a new `shell=True` injection site or weak-hash
regression would pass lint and ship. After: all 18 are fixed (16 by
removing the risk, 2 kept as justified suppressions) and any **new**
HIGH finding now fails `util/lint.py --bandit`.

### How each finding was handled

**Fixed by removing the risk (16):** `shell=True` string commands
converted to `shell=False` args-lists.
- `util.py` / `cli.py` port-kill helpers: run `netstat`/`lsof` bare and
filter output in Python instead of piping through the shell;
`taskkill`/`kill` take args-lists. Port inputs are `int()`-validated
first.
- `lemonade_client.py`: `os.system(taskkill …)` → `subprocess.run([...],
shell=False)` (B605).
- `logger.py`: `chcp` (a cmd.exe builtin) → `cmd /c chcp`.
- `ui/build.py`: `npm` calls (`.cmd` shims) → `cmd /c npm …` on Windows,
bare on other platforms.
- `cli.py` mailto opener: `start "" <url>` → `os.startfile()`
(ShellExecute, no shell parsing) — this one mattered because the URL is
user-built.
- `context7_cache.py`: MD5 is a cache key, fixed with
`usedforsecurity=False` (B324).

**Kept as justified suppressions (2)** — inline `# nosec B602` + a
matching entry in `.security-suppressions.json`:
- `agents/tools/shell_tools.py` — sandboxed shell executor; every
command (and pipeline segment) is whitelist-validated before running,
and `shell=True` is Windows-only so cmd.exe can resolve built-ins/pipes
the tool exists to run.
- `mcp/client/transports/stdio.py` — legacy `from_command()` accepts a
full shell command **string** (documented contract), needs shell
parsing; command is trusted SDK config, and modern `from_config()`
already runs `shell=False`.

### The gate
`util/check_security_gates.py` adds `new_bandit_highs(results,
baseline)`, keyed by `(normalized path, test_id)` — never line number,
so cosmetic line shifts don't trip it. Wired into `util/lint.py`'s
`check_bandit()`; `.bandit-baseline.json` ships as an empty allowlist so
**any** HIGH fails.

### Test plan
- [x] `python -m bandit -r src/gaia -ll -f json` → 0 HIGH findings
- [x] `python util/lint.py --bandit` → PASS
- [x] Negative check: adding a `subprocess.run(f"echo {x}", shell=True)`
probe makes the gate exit 1; passes again once removed
- [x] `pytest tests/unit/test_check_security_gates.py` → 18 passed
- [x] `pytest tests/unit/test_webui_build.py tests/unit/mcp/client/
tests/unit/test_shell_guardrails.py` → pass
- [x] Positive-path functional test: started a real listener, confirmed
the converted `netstat` detection + `taskkill` args-list finds and kills
it and frees the port
- [x] `black`/`isort` clean on all changed files

---------

Co-authored-by: Ovtcharov <kovtchar@amd.com>

Author: kovtcharov-amd

.bandit-baseline.json

@@ -0,0 +1,4 @@
+{
+  "_comment": "Allowlist of accepted bandit HIGH-severity findings, keyed by (path, test_id) — line numbers are intentionally NOT part of the key. Empty means ANY HIGH finding fails the gate. All 18 pre-existing HIGH findings were fixed or converted to justified inline `# nosec` (see .security-suppressions.json); keep this empty unless a genuinely unavoidable HIGH is reviewed and accepted.",
+  "findings": []
+}

.security-suppressions.json

@@ -0,0 +1,15 @@
+{
+  "_comment": "Justified security suppressions. Every inline `# nosec S<n>` / `# nosec B<n>` marker in src/gaia MUST have a matching entry here with a real justification. Do not blanket-suppress to quiet the scanner.",
+  "suppressions": [
+    {
+      "path": "src/gaia/agents/tools/shell_tools.py",
+      "rule": "B602",
+      "justification": "Sandboxed shell tool. Every command (and each pipeline segment) is validated against a whitelist via _validate_command before execution; shell=True is enabled ONLY on Windows so cmd.exe can resolve built-ins (dir/cd/type) and pipes that Git-for-Windows tools rely on. Converting to args-list would break piped/whitelisted commands the tool exists to run."
+    },
+    {
+      "path": "src/gaia/mcp/client/transports/stdio.py",
+      "rule": "B602",
+      "justification": "Legacy from_command() API accepts a full shell command STRING (documented contract, e.g. commands using pipes/env-expansion) and needs shell parsing. Command is caller-supplied SDK config, not external/untrusted input; modern from_config() passes an args list and runs shell=False."
+    }
+  ]
+}

src/gaia/agents/tools/shell_tools.py

@@ -644,7 +644,7 @@ def run_shell_command(
                         timeout=timeout,
                         check=False,
                         env=os.environ.copy(),
-                        shell=use_shell,
+                        shell=use_shell,  # nosec B602 - Windows-only; command whitelist-validated above, shell needed for cmd.exe built-ins/pipes
                     )
                     duration = time.monotonic() - start_time
 

src/gaia/cli.py

@@ -3653,9 +3653,11 @@ def main():
                         system = platform.system()
                         try:
                             if system == "Windows":
-                                subprocess.run(
-                                    ["start", "", mailto_url], shell=True, check=True
-                                )
+                                # os.startfile uses ShellExecute (no shell parsing),
+                                # safe for the user-built mailto URL (which contains
+                                # '&'-separated query params cmd would mis-parse).
+                                # Windows-only attr; guarded by the platform check.
+                                os.startfile(mailto_url)  # pylint: disable=no-member
                             elif system == "Darwin":  # macOS
                                 subprocess.run(["open", mailto_url], check=True)
                             else:  # Linux/Unix
@@ -4776,11 +4778,14 @@ def main():
 
 def kill_process_by_port(port):
     """Find and kill a process running on a specific port."""
+    try:
+        port = int(port)
+    except (ValueError, TypeError):
+        return {"success": False, "message": f"Invalid port number: {port!r}"}
     try:
         if sys.platform.startswith("win"):
-            # Windows implementation
-            cmd = f"netstat -ano | findstr :{port}"
-            output = subprocess.check_output(cmd, shell=True).decode()
+            # Windows implementation (filter netstat output in Python, no shell pipe)
+            output = subprocess.check_output(["netstat", "-ano"]).decode()
             if output:
                 # Split output into lines and process each line
                 for line in output.strip().split("\n"):
@@ -4792,7 +4797,9 @@ def kill_process_by_port(port):
                             pid = int(parts[-1])
                             if pid > 0:  # Ensure we don't try to kill PID 0
                                 subprocess.run(
-                                    f"taskkill /PID {pid} /F", shell=True, check=True
+                                    ["taskkill", "/PID", str(pid), "/F"],
+                                    shell=False,
+                                    check=True,
                                 )
                                 return {
                                     "success": True,
@@ -4808,16 +4815,19 @@ def kill_process_by_port(port):
             # Linux/Unix implementation
             try:
                 # Use lsof to find process using the port
-                cmd = f"lsof -ti:{port}"
-                output = subprocess.check_output(cmd, shell=True).decode().strip()
+                output = (
+                    subprocess.check_output(["lsof", f"-ti:{port}"]).decode().strip()
+                )
                 if output:
                     pids = output.split("\n")
                     killed_pids = []
                     for pid_str in pids:
                         try:
                             pid = int(pid_str.strip())
                             if pid > 0:
-                                subprocess.run(f"kill -9 {pid}", shell=True, check=True)
+                                subprocess.run(
+                                    ["kill", "-9", str(pid)], shell=False, check=True
+                                )
                                 killed_pids.append(str(pid))
                         except (ValueError, subprocess.CalledProcessError):
                             continue
@@ -4834,8 +4844,8 @@ def kill_process_by_port(port):
                 # If lsof is not available, try netstat + ps approach
                 try:
                     # Use netstat to find the port, then extract PID
-                    cmd = f"netstat -tulpn | grep :{port}"
-                    output = subprocess.check_output(cmd, shell=True).decode()
+                    # (filter output in Python, no shell pipe)
+                    output = subprocess.check_output(["netstat", "-tulpn"]).decode()
                     if output:
                         for line in output.strip().split("\n"):
                             if f":{port}" in line:
@@ -4847,8 +4857,8 @@ def kill_process_by_port(port):
                                             pid = int(part.split("/")[0])
                                             if pid > 0:
                                                 subprocess.run(
-                                                    f"kill -9 {pid}",
-                                                    shell=True,
+                                                    ["kill", "-9", str(pid)],
+                                                    shell=False,
                                                     check=True,
                                                 )
                                                 return {

src/gaia/llm/lemonade_client.py

@@ -1109,7 +1109,17 @@ def terminate_server(self):
                 # For subprocess.Popen
                 if sys.platform.startswith("win") and self.server_process.pid:
                     # On Windows, use taskkill to ensure process tree is terminated
-                    os.system(f"taskkill /F /PID {self.server_process.pid} /T")
+                    subprocess.run(
+                        [
+                            "taskkill",
+                            "/F",
+                            "/PID",
+                            str(self.server_process.pid),
+                            "/T",
+                        ],
+                        shell=False,
+                        check=False,
+                    )
                 elif self.server_process.pid:
                     # On Linux/Unix, kill the process group to terminate child processes
                     try:

src/gaia/logger.py

@@ -23,8 +23,12 @@ def configure_console_encoding():
 
             # Also try to set the console code page to UTF-8
             try:
+                # chcp is a cmd.exe builtin; invoke via cmd /c so we avoid shell=True
                 subprocess.run(
-                    ["chcp", "65001"], capture_output=True, shell=True, check=False
+                    ["cmd", "/c", "chcp", "65001"],
+                    capture_output=True,
+                    shell=False,
+                    check=False,
                 )
             except (subprocess.SubprocessError, OSError, FileNotFoundError):
                 pass  # Ignore if chcp command fails

src/gaia/mcp/client/transports/stdio.py

@@ -80,9 +80,13 @@ def connect(self) -> bool:
                 merged_env = os.environ.copy()
                 merged_env.update(self.env)
 
+            # Legacy from_command() path passes a full shell command string
+            # (documented contract) and needs shell parsing; modern from_config()
+            # passes an args list and runs shell=False. Command is caller-supplied
+            # SDK config, not external/untrusted input.
             self._process = subprocess.Popen(
                 cmd,
-                shell=use_shell,
+                shell=use_shell,  # nosec B602 - legacy shell-string API, trusted SDK config
                 stdin=subprocess.PIPE,
                 stdout=subprocess.PIPE,
                 stderr=subprocess.PIPE,

src/gaia/mcp/context7_cache.py

@@ -114,7 +114,7 @@ def _doc_cache_file(self, library: str, query: str) -> Path:
             Path to cache file
         """
         key = f"{library}:{query}"
-        hash_key = hashlib.md5(key.encode()).hexdigest()[:12]
+        hash_key = hashlib.md5(key.encode(), usedforsecurity=False).hexdigest()[:12]
         safe_lib = library.replace("/", "_").replace(".", "_")
         return self.docs_dir / f"{safe_lib}_{hash_key}.json"
 

src/gaia/ui/build.py

@@ -79,20 +79,24 @@ def ensure_webui_built(log_fn=print, warn_fn=None, _webui_dir=None):
         warn_fn("Warning: npm not found. Cannot auto-rebuild Agent UI frontend.")
         return False
 
-    # On Windows, npm is a .cmd batch file requiring shell execution
-    _shell = sys.platform == "win32"
+    # On Windows npm is a .cmd batch file, which CreateProcess can't launch
+    # directly; invoke via `cmd /c` (args are static) so we avoid shell=True.
+    def _npm(*args):
+        if sys.platform == "win32":
+            return ["cmd", "/c", "npm", *args]
+        return ["npm", *args]
 
     # Step 1 — npm install (only if node_modules/ missing)
     if not (webui_dir / "node_modules").is_dir():
         log_fn("Installing Agent UI frontend dependencies...")
         try:
             subprocess.run(
-                ["npm", "install"],
+                _npm("install"),
                 cwd=str(webui_dir),
                 check=True,
                 capture_output=True,
                 text=True,
-                shell=_shell,
+                shell=False,
             )
         except subprocess.CalledProcessError as e:
             warn_fn(f"Warning: npm install failed: {e.stderr}")
@@ -106,10 +110,10 @@ def ensure_webui_built(log_fn=print, warn_fn=None, _webui_dir=None):
     log_fn("Building Agent UI frontend...")
     try:
         subprocess.run(
-            ["npm", "run", "build"],
+            _npm("run", "build"),
             cwd=str(webui_dir),
             check=True,
-            shell=_shell,
+            shell=False,
         )
         log_fn("Agent UI frontend built successfully.")
         return True

src/gaia/util.py

@@ -15,10 +15,10 @@ def kill_process_on_port(port):
         raise ValueError(f"Invalid port number: {port!r}")
     try:
         if sys.platform.startswith("win"):
-            # Windows: use netstat + taskkill
+            # Windows: use netstat + taskkill (filter output in Python, no shell pipe)
             result = subprocess.run(
-                f"netstat -ano | findstr :{port}",
-                shell=True,
+                ["netstat", "-ano"],
+                shell=False,
                 capture_output=True,
                 text=True,
                 check=False,
@@ -39,7 +39,7 @@ def kill_process_on_port(port):
                     print(f"Found process with PID {pid} on port {port}")
                     try:
                         subprocess.run(
-                            f"taskkill /F /PID {pid}", shell=True, check=False
+                            ["taskkill", "/F", "/PID", pid], shell=False, check=False
                         )
                         print(f"Killed process with PID {pid}")
                     except Exception as e:
@@ -50,8 +50,8 @@ def kill_process_on_port(port):
         else:
             # Unix/macOS: use lsof + kill
             result = subprocess.run(
-                f"lsof -ti :{port}",
-                shell=True,
+                ["lsof", "-ti", f":{port}"],
+                shell=False,
                 capture_output=True,
                 text=True,
                 check=False,
@@ -64,7 +64,9 @@ def kill_process_on_port(port):
                     if pid:
                         print(f"Found process with PID {pid} on port {port}")
                         try:
-                            subprocess.run(f"kill -9 {pid}", shell=True, check=False)
+                            subprocess.run(
+                                ["kill", "-9", pid], shell=False, check=False
+                            )
                             print(f"Killed process with PID {pid}")
                         except Exception as e:
                             print(f"Error killing PID {pid}: {e}")