The OSINT investigator's workbench. One case, one folder, every tool. Local-first: your media and your investigations never leave your machine.
JavaScript
#!/usr/bin/env python3
"""Rebuild and relaunch the local Azimut checkout on any supported OS.
The tool supervises the process it starts and exposes a token-protected local
control socket. A later invocation can therefore stop that exact process
without scanning process names or killing unrelated Vite/Azimut instances.
When that handshake finds nothing (a server started by hand, or one whose
launcher was killed hard), the port itself is reclaimed: whoever still listens
on it is stopped so the relaunch never hits "address already in use".
``--ext`` hands the capture extension to the same loop: once the server answers,
`devext.py` loads it into a dev Chrome and Firefox and pairs it with the running
app, and ``--watch-ext`` reloads it there on every save.
"""
from __future__ import annotations
import argparse
import json
import os
import secrets
import shutil
import signal
import socket
import subprocess
import sys
import threading
import time
from pathlib import Path
from typing import Any
ROOT = Path(__file__).resolve().parent.parent
STATE_PATH = ROOT / ".azimut-relaunch.json"
def _read_state(path: Path) -> dict[str, Any] | None:
try:
data = json.loads(path.read_text(encoding="utf-8"))
except (OSError, json.JSONDecodeError):
return None
if not isinstance(data, dict):
return None
port = data.get("port")
token = data.get("token")
if not isinstance(port, int) or not 1 <= port <= 65535:
return None
if not isinstance(token, str) or len(token) != 64:
return None
return {"port": port, "token": token}
def _remove_owned_state(path: Path, token: str) -> None:
state = _read_state(path)
if state and state["token"] == token:
path.unlink(missing_ok=True)
class _ControlServer:
"""Accept a stop request from the next relaunch invocation."""
def __init__(self, state_path: Path) -> None:
self.state_path = state_path
self.token = secrets.token_hex(32)
self.stop_requested = threading.Event()
self._socket = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
self._socket.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
self._socket.bind(("127.0.0.1", 0))
self._socket.listen(1)
self._socket.settimeout(0.25)
self.port = int(self._socket.getsockname()[1])
self._thread = threading.Thread(target=self._serve, daemon=True)
def start(self) -> None:
temp = self.state_path.with_name(f"{self.state_path.name}.{self.token}.tmp")
temp.write_text(
json.dumps({"port": self.port, "token": self.token}),
encoding="utf-8",
)
try:
temp.chmod(0o600)
except OSError:
pass
os.replace(temp, self.state_path)
self._thread.start()
def _serve(self) -> None:
while not self.stop_requested.is_set():
try:
connection, _ = self._socket.accept()
except TimeoutError:
continue
except OSError:
return
with connection:
connection.settimeout(1)
try:
supplied = connection.recv(128).decode("ascii").strip()
except (OSError, UnicodeError):
continue
if secrets.compare_digest(supplied, self.token):
connection.sendall(b"OK\n")
self.stop_requested.set()
def close(self) -> None:
self.stop_requested.set()
self._socket.close()
if self._thread.is_alive() and self._thread is not threading.current_thread():
self._thread.join(timeout=1)
_remove_owned_state(self.state_path, self.token)
def _stop_previous(path: Path, timeout: float = 10) -> bool:
state = _read_state(path)
if state is None:
path.unlink(missing_ok=True)
return False
try:
with socket.create_connection(("127.0.0.1", state["port"]), timeout=1) as connection:
connection.sendall(f"{state['token']}\n".encode("ascii"))
if connection.recv(16).strip() != b"OK":
raise RuntimeError("the previous launcher rejected the stop request")
except OSError:
_remove_owned_state(path, state["token"])
return False
deadline = time.monotonic() + timeout
while path.exists() and time.monotonic() < deadline:
time.sleep(0.05)
if path.exists():
raise RuntimeError("the previous launcher did not stop within 10 seconds")
return True
def _probe_reuses_address(platform: str = os.name) -> bool:
"""Whether the probe binds the way the server will.
On POSIX the server sets SO_REUSEADDR, so the probe must too: connections
left in TIME-WAIT block a plain bind long after the server is gone, and the
port would look busy forever. On Windows the same option lets a bind steal a
live listener, which would report a busy port as free.
"""
return platform != "nt"
def _port_is_free(port: int) -> bool:
with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as probe:
if _probe_reuses_address():
probe.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
try:
probe.bind(("127.0.0.1", port))
except OSError:
return False
return True
def _command_output(command: list[str]) -> str:
if not shutil.which(command[0]):
return ""
try:
result = subprocess.run(
command, capture_output=True, text=True, timeout=10, check=False
)
except (OSError, subprocess.SubprocessError):
return ""
return result.stdout
def _listener_pids(port: int, platform: str = os.name) -> set[int]:
"""Processes listening on the port, best effort and never fatal."""
pids: set[int] = set()
if platform == "nt":
for line in _command_output(["netstat", "-a", "-n", "-o", "-p", "TCP"]).splitlines():
fields = line.split()
if len(fields) < 5 or fields[3].upper() != "LISTENING":
continue
if fields[1].rsplit(":", 1)[-1] != str(port):
continue
if fields[4].isdigit():
pids.add(int(fields[4]))
return pids
output = _command_output(
["lsof", "-t", "-n", "-P", f"-iTCP:{port}", "-sTCP:LISTEN"]
)
for token in output.split():
if token.isdigit():
pids.add(int(token))
if pids:
return pids
# lsof is missing on plenty of Linux installs; ss ships with iproute2.
for line in _command_output(["ss", "-H", "-l", "-t", "-n", "-p", "-a"]).splitlines():
fields = line.split()
if len(fields) < 4 or fields[3].rsplit(":", 1)[-1] != str(port):
continue
for chunk in line.split("pid=")[1:]:
digits = chunk.split(",")[0].split(")")[0]
if digits.isdigit():
pids.add(int(digits))
return pids
def _kill_pid(pid: int, *, force: bool) -> None:
if os.name == "nt":
command = ["taskkill", "/PID", str(pid), "/T"]
if force:
command.append("/F")
subprocess.run(
command, check=False, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL
)
return
try:
os.kill(pid, signal.SIGKILL if force else signal.SIGTERM)
except OSError:
pass
def _free_port(port: int, timeout: float = 10) -> list[int]:
"""Stop whatever still listens on the port. Returns the PIDs stopped."""
if _port_is_free(port):
return []
stopped: list[int] = []
deadline = time.monotonic() + timeout
forced = False
while True:
for pid in sorted(_listener_pids(port)):
if pid == os.getpid():
continue
_kill_pid(pid, force=forced)
if pid not in stopped:
stopped.append(pid)
for _ in range(20):
if _port_is_free(port):
return stopped
time.sleep(0.05)
if time.monotonic() >= deadline:
break
forced = True
if stopped:
raise RuntimeError(f"port {port} is still held by {stopped} after a kill")
raise RuntimeError(
f"port {port} is in use and its owner could not be identified; "
"stop it by hand or relaunch with --port"
)
def _venv_python(root: Path, platform: str = os.name) -> Path:
relative = Path("Scripts/python.exe") if platform == "nt" else Path("bin/python")
python = root / ".venv" / relative
if not python.is_file():
raise RuntimeError(f"virtual environment not found at {python}; create .venv first")
return python
def _npm_build_command(platform: str = os.name) -> list[str]:
npm = shutil.which("npm")
if not npm:
raise RuntimeError("npm was not found on PATH; install Node.js 20 or newer")
if platform == "nt" and Path(npm).suffix.lower() in {".cmd", ".bat"}:
command = os.environ.get("COMSPEC", "cmd.exe")
return [command, "/d", "/s", "/c", npm, "run", "build"]
return [npm, "run", "build"]
def _spawn(command: list[str], cwd: Path) -> subprocess.Popen[bytes]:
if os.name == "nt":
return subprocess.Popen(
command,
cwd=cwd,
# Read by name: the constant is Windows-only, so a type-checker running on
# Linux does not know the attribute exists. Zero is what Windows means by
# "no extra creation flags", and this branch never runs anywhere else.
creationflags=getattr(subprocess, "CREATE_NEW_PROCESS_GROUP", 0),
)
return subprocess.Popen(command, cwd=cwd, start_new_session=True)
def _terminate(process: subprocess.Popen[bytes]) -> None:
if process.poll() is not None:
return
if os.name == "nt":
subprocess.run(
["taskkill", "/PID", str(process.pid), "/T", "/F"],
check=False,
stdout=subprocess.DEVNULL,
stderr=subprocess.DEVNULL,
)
else:
try:
os.killpg(process.pid, signal.SIGTERM)
except ProcessLookupError:
return
try:
process.wait(timeout=5)
except subprocess.TimeoutExpired:
if os.name == "nt":
process.kill()
else:
try:
os.killpg(process.pid, signal.SIGKILL)
except ProcessLookupError:
pass
process.wait(timeout=5)
def _run_process(
command: list[str], cwd: Path, stop_requested: threading.Event
) -> int | None:
process = _spawn(command, cwd)
try:
while process.poll() is None:
if stop_requested.wait(0.2):
_terminate(process)
return None
return process.returncode
except BaseException:
_terminate(process)
raise
def _load_devext() -> Any:
"""Import the sibling script by path, so pytest can load this one by path too."""
directory = str(Path(__file__).resolve().parent)
if directory not in sys.path:
sys.path.insert(0, directory)
import devext
return devext
def _serve_extension(
browsers: list[str], port: int, watch: bool, stop_requested: threading.Event
) -> None:
"""Wait for the server, then load the extension into the dev browsers.
Pairing reads the token from the running app, so this waits for the port the
frontend build is still delaying. A failure here never stops the app.
"""
devext = _load_devext()
deadline = time.monotonic() + 300
while _port_is_free(port):
if stop_requested.wait(0.3) or time.monotonic() > deadline:
return
options = devext.Options(browsers=browsers, url=f"http://127.0.0.1:{port}")
try:
devext.sync(options)
if watch:
devext.watch(options, stop_requested)
except (RuntimeError, OSError) as exc:
print(f"extension: {exc}", file=sys.stderr)
def run(
*,
port: int,
no_browser: bool,
extension_browsers: list[str] | None = None,
watch_extension: bool = False,
) -> int:
if _stop_previous(STATE_PATH):
print("Stopped the previous managed Azimut instance.")
stopped = _free_port(port)
if stopped:
joined = ", ".join(str(pid) for pid in stopped)
print(f"Freed port {port} (stopped {joined}).")
control = _ControlServer(STATE_PATH)
control.start()
try:
print("Rebuilding the frontend...")
result = _run_process(_npm_build_command(), ROOT / "frontend", control.stop_requested)
if result is None:
return 0
if result != 0:
return result
command = [str(_venv_python(ROOT)), "-m", "azimut.cli", "--port", str(port)]
if no_browser:
command.append("--no-browser")
if extension_browsers:
threading.Thread(
target=_serve_extension,
args=(extension_browsers, port, watch_extension, control.stop_requested),
daemon=True,
).start()
print(f"Starting Azimut on http://127.0.0.1:{port}")
result = _run_process(command, ROOT, control.stop_requested)
return 0 if result is None else result
finally:
control.close()
def extension_browsers(choice: str | None, watch: bool) -> list[str] | None:
"""Which dev browsers to sync, or None when --ext was not asked for."""
if choice is None:
return ["chrome", "firefox"] if watch else None
return ["chrome", "firefox"] if choice == "all" else [choice]
def main() -> int:
parser = argparse.ArgumentParser(
description="Rebuild the frontend and relaunch the local Azimut checkout"
)
parser.add_argument("--port", type=int, default=8477)
parser.add_argument("--no-browser", action="store_true")
parser.add_argument(
"--ext",
nargs="?",
const="all",
choices=["chrome", "firefox", "all"],
help="load and pair the capture extension in a dev browser (see devext.py)",
)
parser.add_argument(
"--watch-ext",
action="store_true",
help="keep reloading the extension on every save (implies --ext)",
)
args = parser.parse_args()
if not 1 <= args.port <= 65535:
parser.error("--port must be between 1 and 65535")
try:
return run(
port=args.port,
no_browser=args.no_browser,
extension_browsers=extension_browsers(args.ext, args.watch_ext),
watch_extension=args.watch_ext,
)
except RuntimeError as exc:
print(f"error: {exc}", file=sys.stderr)
return 1
except KeyboardInterrupt:
return 130
if __name__ == "__main__":
raise SystemExit(main())