sosya 0.0.1__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.
sosya/__init__.py ADDED
@@ -0,0 +1,3 @@
1
+ """Sosya: describe a hacking lab in plain English, get it running, isolated and verified."""
2
+
3
+ __version__ = "0.0.1"
sosya/__main__.py ADDED
@@ -0,0 +1,5 @@
1
+ """Allow `python -m sosya`."""
2
+
3
+ from sosya.cli import app
4
+
5
+ app(prog_name="sosya")
sosya/cli.py ADDED
@@ -0,0 +1,116 @@
1
+ """Command-line interface for Sosya."""
2
+
3
+ from typing import Annotated
4
+
5
+ import typer
6
+ from rich.console import Console
7
+ from rich.table import Table
8
+
9
+ from sosya import __version__
10
+ from sosya.doctor import CheckResult, Status, run_checks
11
+
12
+ app = typer.Typer(
13
+ name="sosya",
14
+ help="Describe a hacking lab in plain English. Get it running, isolated and verified.",
15
+ no_args_is_help=True,
16
+ add_completion=False,
17
+ )
18
+ console = Console()
19
+
20
+ RangeArg = Annotated[
21
+ str, typer.Argument(metavar="RANGE", help="Range name or path to a range.yaml.")
22
+ ]
23
+
24
+ _STATUS_LABEL = {
25
+ Status.OK: "[green]ok[/]",
26
+ Status.WARN: "[yellow]warn[/]",
27
+ Status.FAIL: "[red]fail[/]",
28
+ }
29
+
30
+
31
+ def _version(value: bool) -> None:
32
+ if value:
33
+ console.print(f"sosya {__version__}")
34
+ raise typer.Exit()
35
+
36
+
37
+ @app.callback()
38
+ def main(
39
+ version: Annotated[
40
+ bool,
41
+ typer.Option(
42
+ "--version", callback=_version, is_eager=True, help="Show the version and exit."
43
+ ),
44
+ ] = False,
45
+ ) -> None:
46
+ """Sosya builds isolated, verified security labs from a single sentence."""
47
+
48
+
49
+ def _not_yet(command: str) -> None:
50
+ console.print(f"[yellow]sosya {command}[/] is not implemented yet: it is planned for v0.1.")
51
+ raise typer.Exit(code=1)
52
+
53
+
54
+ @app.command()
55
+ def new(
56
+ description: Annotated[str, typer.Argument(help="The lab you want, in plain English.")],
57
+ ) -> None:
58
+ """Plan a range from a description, then build and validate it."""
59
+ _not_yet("new")
60
+
61
+
62
+ @app.command()
63
+ def up(name: RangeArg) -> None:
64
+ """Start a range from its range.yaml. No LLM needed."""
65
+ _not_yet("up")
66
+
67
+
68
+ @app.command()
69
+ def down(name: RangeArg) -> None:
70
+ """Stop a range and remove its containers and networks."""
71
+ _not_yet("down")
72
+
73
+
74
+ @app.command()
75
+ def status() -> None:
76
+ """List running ranges and the health of their services."""
77
+ _not_yet("status")
78
+
79
+
80
+ @app.command()
81
+ def shell(name: RangeArg) -> None:
82
+ """Open a shell in the range's Kali attacker box."""
83
+ _not_yet("shell")
84
+
85
+
86
+ @app.command()
87
+ def validate(name: RangeArg) -> None:
88
+ """Re-run every check on an existing range."""
89
+ _not_yet("validate")
90
+
91
+
92
+ @app.command()
93
+ def catalog(
94
+ query: Annotated[str | None, typer.Argument(help="Words to search for.")] = None,
95
+ ) -> None:
96
+ """Search the available vulnerable environments."""
97
+ _not_yet("catalog")
98
+
99
+
100
+ @app.command()
101
+ def doctor() -> None:
102
+ """Check Docker, Compose v2, CPU architecture and LLM configuration."""
103
+ results = run_checks()
104
+ _print_checks(results)
105
+ if any(result.status is Status.FAIL for result in results):
106
+ raise typer.Exit(code=1)
107
+
108
+
109
+ def _print_checks(results: list[CheckResult]) -> None:
110
+ table = Table(title="sosya doctor", title_justify="left", header_style="bold")
111
+ table.add_column("Check")
112
+ table.add_column("Status")
113
+ table.add_column("Details", overflow="fold")
114
+ for result in results:
115
+ table.add_row(result.name, _STATUS_LABEL[result.status], result.detail)
116
+ console.print(table)
sosya/doctor.py ADDED
@@ -0,0 +1,121 @@
1
+ """Environment checks behind `sosya doctor`."""
2
+
3
+ import os
4
+ import platform
5
+ import shutil
6
+ import subprocess
7
+ import sys
8
+ from dataclasses import dataclass
9
+ from enum import Enum
10
+
11
+ MIN_PYTHON = (3, 12)
12
+ LLM_ENV_VARS = ("ANTHROPIC_API_KEY", "OPENAI_API_KEY", "OPENAI_BASE_URL")
13
+
14
+
15
+ class Status(Enum):
16
+ OK = "ok"
17
+ WARN = "warn"
18
+ FAIL = "fail"
19
+
20
+
21
+ @dataclass(frozen=True)
22
+ class CheckResult:
23
+ name: str
24
+ status: Status
25
+ detail: str
26
+
27
+
28
+ def _run(cmd: list[str], timeout: float = 10.0) -> subprocess.CompletedProcess[str] | None:
29
+ """Run a command; return None if it cannot start or does not finish in time."""
30
+ try:
31
+ return subprocess.run(cmd, capture_output=True, text=True, timeout=timeout, check=False)
32
+ except (OSError, subprocess.TimeoutExpired):
33
+ return None
34
+
35
+
36
+ def _last_line(text: str) -> str:
37
+ lines = [line for line in text.strip().splitlines() if line.strip()]
38
+ return lines[-1] if lines else "no output"
39
+
40
+
41
+ def check_python() -> CheckResult:
42
+ version = ".".join(str(part) for part in sys.version_info[:3])
43
+ if sys.version_info[:2] < MIN_PYTHON:
44
+ return CheckResult("Python", Status.FAIL, f"{version}: Sosya needs 3.12 or newer")
45
+ return CheckResult("Python", Status.OK, version)
46
+
47
+
48
+ def check_docker_cli() -> CheckResult:
49
+ path = shutil.which("docker")
50
+ if path is None:
51
+ return CheckResult(
52
+ "Docker CLI",
53
+ Status.FAIL,
54
+ "docker not found on PATH: install Docker Engine or Docker Desktop",
55
+ )
56
+ return CheckResult("Docker CLI", Status.OK, path)
57
+
58
+
59
+ def check_docker_daemon() -> CheckResult:
60
+ if shutil.which("docker") is None:
61
+ return CheckResult("Docker daemon", Status.FAIL, "skipped: docker CLI not found")
62
+ proc = _run(["docker", "info", "--format", "{{.ServerVersion}}"])
63
+ if proc is None:
64
+ return CheckResult("Docker daemon", Status.FAIL, "docker info did not answer in time")
65
+ if proc.returncode != 0:
66
+ return CheckResult(
67
+ "Docker daemon",
68
+ Status.FAIL,
69
+ f"not reachable ({_last_line(proc.stderr)}): is Docker running for your user?",
70
+ )
71
+ return CheckResult("Docker daemon", Status.OK, f"server {proc.stdout.strip()}")
72
+
73
+
74
+ def check_compose() -> CheckResult:
75
+ if shutil.which("docker") is None:
76
+ return CheckResult("Docker Compose v2", Status.FAIL, "skipped: docker CLI not found")
77
+ proc = _run(["docker", "compose", "version", "--short"])
78
+ if proc is None or proc.returncode != 0:
79
+ return CheckResult(
80
+ "Docker Compose v2",
81
+ Status.FAIL,
82
+ "`docker compose` is missing: install the Compose v2 plugin",
83
+ )
84
+ return CheckResult("Docker Compose v2", Status.OK, proc.stdout.strip())
85
+
86
+
87
+ def check_architecture() -> CheckResult:
88
+ machine = platform.machine().lower()
89
+ if machine in {"x86_64", "amd64"}:
90
+ return CheckResult("CPU architecture", Status.OK, machine)
91
+ if machine in {"arm64", "aarch64"}:
92
+ return CheckResult(
93
+ "CPU architecture",
94
+ Status.WARN,
95
+ f"{machine}: Vulhub images may be amd64-only and run slowly or break under emulation",
96
+ )
97
+ return CheckResult("CPU architecture", Status.WARN, f"{machine}: untested architecture")
98
+
99
+
100
+ def check_llm() -> CheckResult:
101
+ configured = [name for name in LLM_ENV_VARS if os.environ.get(name)]
102
+ if not configured:
103
+ return CheckResult(
104
+ "LLM provider",
105
+ Status.WARN,
106
+ "none configured: set ANTHROPIC_API_KEY, OPENAI_API_KEY or OPENAI_BASE_URL "
107
+ "(e.g. Ollama). `sosya up` works without one.",
108
+ )
109
+ # Report which variables are set, never their values.
110
+ return CheckResult("LLM provider", Status.OK, ", ".join(configured) + " set")
111
+
112
+
113
+ def run_checks() -> list[CheckResult]:
114
+ return [
115
+ check_python(),
116
+ check_docker_cli(),
117
+ check_docker_daemon(),
118
+ check_compose(),
119
+ check_architecture(),
120
+ check_llm(),
121
+ ]
@@ -0,0 +1,70 @@
1
+ Metadata-Version: 2.5
2
+ Name: sosya
3
+ Version: 0.0.1
4
+ Summary: Describe a hacking lab in plain English. Get it running, isolated and verified.
5
+ License-Expression: MIT
6
+ License-File: LICENSE
7
+ Keywords: ctf,cyber-range,docker,lab,llm,security,training,vulhub
8
+ Classifier: Development Status :: 2 - Pre-Alpha
9
+ Classifier: Environment :: Console
10
+ Classifier: Intended Audience :: Education
11
+ Classifier: Intended Audience :: Information Technology
12
+ Classifier: Intended Audience :: System Administrators
13
+ Classifier: Operating System :: MacOS
14
+ Classifier: Operating System :: POSIX :: Linux
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3.12
17
+ Classifier: Programming Language :: Python :: 3.13
18
+ Classifier: Programming Language :: Python :: 3.14
19
+ Classifier: Topic :: Security
20
+ Requires-Python: >=3.12
21
+ Requires-Dist: pydantic>=2.14
22
+ Requires-Dist: pyyaml>=6.0.3
23
+ Requires-Dist: rich>=15.0
24
+ Requires-Dist: typer>=0.29
25
+ Description-Content-Type: text/markdown
26
+
27
+ # Sosya
28
+
29
+ **Describe a hacking lab in plain English. Get it running, isolated and verified.**
30
+
31
+ > Status: pre-release. Sosya v0.1 ships on November 24, 2026.
32
+
33
+ Sosya turns one sentence into a working, multi-container security lab. It builds it from real,
34
+ documented vulnerable environments ([Vulhub](https://github.com/vulhub/vulhub)), checks that it
35
+ actually works, and keeps it isolated from your network by default.
36
+
37
+ ```console
38
+ $ sosya new "Struts2 app in a DMZ, passwordless Redis reachable only from the web server"
39
+ $ sosya shell dmz-redis # Kali, inside the range network
40
+ ```
41
+
42
+ ## Why Sosya
43
+
44
+ - **Verified.** A range is "ready" only after it boots and every service answers from the
45
+ attacker box.
46
+ - **Safe by default.** No ports published on your host: targets live on internal networks.
47
+ - **Lightweight.** Docker on a laptop. No hypervisor, no dedicated server.
48
+ - **Any LLM.** Anthropic, OpenAI or any OpenAI-compatible endpoint, including local models via
49
+ Ollama.
50
+
51
+ ## Try what exists today
52
+
53
+ From a checkout of this repository, with [uv](https://docs.astral.sh/uv/) installed:
54
+
55
+ ```console
56
+ uv run sosya doctor
57
+ ```
58
+
59
+ ## Responsible use
60
+
61
+ Sosya builds local labs for training and research on systems you own. It does not generate or run
62
+ exploits.
63
+
64
+ ## Credits
65
+
66
+ Vulnerable environments by [Vulhub](https://github.com/vulhub/vulhub), MIT license.
67
+
68
+ ## License
69
+
70
+ [MIT](LICENSE)
@@ -0,0 +1,9 @@
1
+ sosya/__init__.py,sha256=m0uJakVUEBsDnCrKuoBeJL-scHoxOyPrM6jIP582fc0,116
2
+ sosya/__main__.py,sha256=KemNI91cwWE6bD-38pGaQLXhrfYm3BjfCVzE9j65rxM,82
3
+ sosya/cli.py,sha256=X1uj-gzDMd93OE9rH_V68BWtldSdCOnN19Dw4Wa_oRk,2982
4
+ sosya/doctor.py,sha256=j1ZFVWjbmyc1-G1cDqJ1e5P6qWQeAbVFpgQzVNebGx4,3980
5
+ sosya-0.0.1.dist-info/METADATA,sha256=mwe0pdvWeGmKNjzNTNJ-5PXhdwGYQuOSZY9BvTFCDCU,2356
6
+ sosya-0.0.1.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
7
+ sosya-0.0.1.dist-info/entry_points.txt,sha256=gXngBLn4Sb_ghKQSt-txX9_kG7ieaU76_rLM6sD9MRw,40
8
+ sosya-0.0.1.dist-info/licenses/LICENSE,sha256=a4K73hCz5QNIUtJlTIDqCWur1IK7dYLlg33PaGj7m8g,1074
9
+ sosya-0.0.1.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: hatchling 1.33.0
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ sosya = sosya.cli:app
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 The Sosya authors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.