Skip to content

armgit / AiSOC

Public Imported from GitHub
0

Open-source AI Security Operations Center: alert fusion, LLM-agent triage, MITRE ATT&CK investigation, and a replayable decision ledger for every agent step. Self-hostable, runs with no API keys, MIT licensed. Ships an MCP server for Claude, Cursor and Continue.

fix(actions,api): repair Docker boot — AWS SG client import + detection_proposals path resolution (closes #81 #82 #83) (#84)

Beenu Arora01dd1f611ffe
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 285e57ee4..a04e35362 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -278,7 +278,7 @@ jobs:
- uses: actions/checkout@v6
- uses: actions/setup-go@v6
with:
- go-version: '1.24'
+ go-version: '1.25'
cache-dependency-path: services/${{ matrix.service }}/go.sum
- name: Build
run: |
@@ -306,7 +306,7 @@ jobs:
- uses: actions/checkout@v6
- uses: actions/setup-go@v6
with:
- go-version: '1.24'
+ go-version: '1.25'
cache-dependency-path: packages/plugin-sdk-go/go.sum
- name: Build
run: |
diff --git a/services/actions/app/clients/aws_security_groups.py b/services/actions/app/clients/aws_security_groups.py
index 218e970a1..1eda2d48c 100644
--- a/services/actions/app/clients/aws_security_groups.py
+++ b/services/actions/app/clients/aws_security_groups.py
@@ -1,21 +1,23 @@
"""
-AWS Security Groups client for IP blocking/unblocking.
-
-Uses boto3 (installed via the connectors service layer or injected via
-httpx-compatible shim where boto3 is available). Falls back to direct
-AWS EC2 API calls via httpx + SigV4 signing when boto3 is absent so
-the actions service stays dependency-light.
-
-Credentials expected in ActionRequest.parameters:
- aws_access_key_id: str
- aws_secret_access_key: str
- aws_region: str (e.g. "us-east-1")
- aws_security_group_id: str (sg-xxxxxxxx)
- aws_assume_role_arn: str (optional, for cross-account assume-role)
- aws_session_token: str (optional, pre-assumed)
- aws_protocol: str (optional, default "tcp")
- aws_from_port: int (optional, default 0)
- aws_to_port: int (optional, default 65535)
+AWS Security Groups client for IP block / unblock actions.
+
+Used by ``app.executors.network`` to enforce containment via a dedicated AWS
+Security Group. boto3 is the supported transport; when boto3 is unavailable the
+client returns a structured stub so the actions service still boots and the
+executor can fall back to simulation mode.
+
+Credential resolution (all optional — when omitted, boto3 falls back to its
+default chain: env vars, ``~/.aws/credentials``, IAM instance profile, IRSA):
+ region (str) — AWS region, default ``us-east-1``
+ access_key_id (str | None)
+ secret_access_key (str | None)
+ session_token (str | None)
+ security_group_id (str | None) — may be supplied per-call instead
+ role_arn (str | None) — optional cross-account assume-role
+ session_name (str) — STS session name when assuming a role
+
+Both ``AWSSecurityGroupsClient`` and the legacy ``AWSSGClient`` alias are
+exported, so existing callers using either name keep working.
"""
from __future__ import annotations
@@ -27,51 +29,65 @@ import structlog
logger = structlog.get_logger()
-class AWSSGClient:
- """Async AWS Security Group IP block/unblock using boto3 (if available)
- or the raw EC2 REST API via SigV4-signed httpx calls."""
+class AWSSecurityGroupsClient:
+ """Async wrapper around EC2 ``authorize`` / ``revoke`` security-group ingress.
+
+ The class is intentionally tolerant of how callers supply parameters:
+
+ * ``security_group_id`` may be provided at construction *or* passed per-call
+ as ``sg_id=`` (the latter is what ``app.executors.network`` does).
+ * Credentials are optional. If absent, boto3's default credential chain is
+ used (env vars / shared config / IAM role / IRSA), which is the right
+ behaviour for in-cluster deployments.
+ * ``port`` follows AWS conventions: ``-1`` (or ``None``) means "all ports"
+ and is paired with ``IpProtocol="-1"`` for "all protocols".
+ """
def __init__(
self,
- access_key_id: str,
- secret_access_key: str,
- region: str,
- security_group_id: str,
+ *,
+ region: str = "us-east-1",
+ access_key_id: str | None = None,
+ secret_access_key: str | None = None,
session_token: str | None = None,
+ security_group_id: str | None = None,
+ role_arn: str | None = None,
+ session_name: str = "aisoc-actions",
+ # Legacy aliases retained for backward compatibility.
assume_role_arn: str | None = None,
+ sg_id: str | None = None,
) -> None:
+ self._region = region
self._access_key_id = access_key_id
self._secret_access_key = secret_access_key
- self._region = region
- self._sg_id = security_group_id
self._session_token = session_token
- self._assume_role_arn = assume_role_arn
+ self._sg_id = security_group_id or sg_id
+ self._role_arn = role_arn or assume_role_arn
+ self._session_name = session_name
- async def _get_credentials(self) -> tuple[str, str, str | None]:
- """Return (key_id, secret, session_token), assuming a role if configured."""
- if not self._assume_role_arn:
- return self._access_key_id, self._secret_access_key, self._session_token
+ # ------------------------------------------------------------------
+ # Helpers
+ # ------------------------------------------------------------------
- # Assume-role via STS
- try:
- import boto3
+ @staticmethod
+ def _port_range(port: int | None) -> tuple[int, int]:
+ """Translate executor port semantics into AWS ``(FromPort, ToPort)``.
- sts = boto3.client(
- "sts",
- aws_access_key_id=self._access_key_id,
- aws_secret_access_key=self._secret_access_key,
- region_name=self._region,
- )
- creds = sts.assume_role(
- RoleArn=self._assume_role_arn,
- RoleSessionName="aisoc-actions",
- )["Credentials"]
- return creds["AccessKeyId"], creds["SecretAccessKey"], creds["SessionToken"]
- except ImportError:
- logger.warning("aws_sg.boto3_not_available — cannot assume role, using base creds")
- return self._access_key_id, self._secret_access_key, self._session_token
+ ``-1`` and ``None`` mean "all ports", anything else is treated as a
+ single port (FromPort == ToPort == port).
+ """
+ if port is None or port == -1:
+ return -1, -1
+ return port, port
+
+ def _resolve_sg_id(self, sg_id: str | None) -> str:
+ resolved = sg_id or self._sg_id
+ if not resolved:
+ raise ValueError("security_group_id is required (set at construct time or pass sg_id=)")
+ return resolved
- async def _boto3_available(self) -> bool:
+ @staticmethod
+ def _boto3_available() -> bool:
try:
import boto3 # noqa: F401
@@ -79,65 +95,85 @@ class AWSSGClient:
except ImportError:
return False
- async def block_ip(
- self,
- ip: str,
- protocol: str = "tcp",
- from_port: int = 0,
- to_port: int = 65535,
- ) -> dict[str, Any]:
- """Add an ingress deny rule for the IP (via revoke on a permissive SG or by adding egress deny).
+ async def _get_credentials(self) -> tuple[str | None, str | None, str | None]:
+ """Return ``(key_id, secret, token)``, assuming a role if configured.
- NOTE: AWS Security Groups are allow-only and don't support explicit deny rules.
- The idiomatic pattern is to add the IP as an *ingress allow* in a block-list SG
- that has no route to protected resources, or to remove existing allows.
- We implement the explicit revoke-authorization pattern for a dedicated block-SG here.
+ Falls through to the configured static credentials (or ``None`` to let
+ boto3 use its default chain) when assume-role is not requested or when
+ boto3 is unavailable.
"""
- key_id, secret, token = await self._get_credentials()
-
- if await self._boto3_available():
- return await self._boto3_authorize_egress_block(key_id, secret, token, ip, protocol, from_port, to_port)
- else:
- return await self._httpx_authorize(key_id, secret, token, ip, protocol, from_port, to_port, action="block")
+ if not self._role_arn or not self._boto3_available():
+ return self._access_key_id, self._secret_access_key, self._session_token
- async def unblock_ip(
- self,
- ip: str,
- protocol: str = "tcp",
- from_port: int = 0,
- to_port: int = 65535,
- ) -> dict[str, Any]:
- """Remove the ingress deny rule for the IP."""
- key_id, secret, token = await self._get_credentials()
+ import boto3
- if await self._boto3_available():
- return await self._boto3_revoke_block(key_id, secret, token, ip, protocol, from_port, to_port)
- else:
- return await self._httpx_authorize(key_id, secret, token, ip, protocol, from_port, to_port, action="unblock")
+ sts = boto3.client(
+ "sts",
+ aws_access_key_id=self._access_key_id,
+ aws_secret_access_key=self._secret_access_key,
+ region_name=self._region,
+ )
+ creds = sts.assume_role(
+ RoleArn=self._role_arn,
+ RoleSessionName=self._session_name,
+ )["Credentials"]
+ return creds["AccessKeyId"], creds["SecretAccessKey"], creds["SessionToken"]
- async def _boto3_authorize_egress_block(
+ def _ec2(
self,
- key_id: str,
- secret: str,
+ key_id: str | None,
+ secret: str | None,
token: str | None,
- ip: str,
- protocol: str,
- from_port: int,
- to_port: int,
- ) -> dict[str, Any]:
+ ):
import boto3
- ec2 = boto3.client(
+ return boto3.client(
"ec2",
region_name=self._region,
aws_access_key_id=key_id,
aws_secret_access_key=secret,
aws_session_token=token,
)
+
+ @staticmethod
+ def _unavailable(action: str, ip: str) -> dict[str, Any]:
+ logger.warning("aws_sg.boto3_unavailable", action=action, ip=ip)
+ return {
+ "success": False,
+ "action": action,
+ "ip": ip,
+ "note": ("boto3 not installed in actions service — install boto3 to enable live AWS Security Group execution."),
+ }
+
+ # ------------------------------------------------------------------
+ # Public API used by app.executors.network
+ # ------------------------------------------------------------------
+
+ async def block_ip(
+ self,
+ ip: str,
+ *,
+ sg_id: str | None = None,
+ protocol: str = "-1",
+ port: int | None = None,
+ from_port: int | None = None,
+ to_port: int | None = None,
+ ) -> dict[str, Any]:
+ """Authorize an ingress rule for ``ip`` on the dedicated block-list SG."""
+ sg = self._resolve_sg_id(sg_id)
+ if from_port is None or to_port is None:
+ from_port, to_port = self._port_range(port)
+
+ if not self._boto3_available():
+ return self._unavailable("block_ip", ip)
+
+ key_id, secret, token = await self._get_credentials()
+ ec2 = self._ec2(key_id, secret, token)
cidr = f"{ip}/32"
+
try:
ec2.authorize_security_group_ingress(
- GroupId=self._sg_id,
+ GroupId=sg,
IpPermissions=[
{
"IpProtocol": protocol,
@@ -147,37 +183,51 @@ class AWSSGClient:
}
],
)
- logger.info("aws_sg.block_ip.success", sg=self._sg_id, cidr=cidr)
- return {"success": True, "action": "block_ip", "ip": ip, "sg_id": self._sg_id, "cidr": cidr}
+ logger.info("aws_sg.block_ip.success", sg=sg, cidr=cidr)
+ return {
+ "success": True,
+ "action": "block_ip",
+ "ip": ip,
+ "sg_id": sg,
+ "cidr": cidr,
+ }
except ec2.exceptions.ClientError as exc:
code = exc.response["Error"]["Code"]
if code == "InvalidPermission.Duplicate":
- return {"success": True, "action": "block_ip", "ip": ip, "note": "Rule already exists"}
+ return {
+ "success": True,
+ "action": "block_ip",
+ "ip": ip,
+ "sg_id": sg,
+ "note": "Rule already exists",
+ }
raise
- async def _boto3_revoke_block(
+ async def unblock_ip(
self,
- key_id: str,
- secret: str,
- token: str | None,
ip: str,
- protocol: str,
- from_port: int,
- to_port: int,
+ *,
+ sg_id: str | None = None,
+ protocol: str = "-1",
+ port: int | None = None,
+ from_port: int | None = None,
+ to_port: int | None = None,
) -> dict[str, Any]:
- import boto3
+ """Revoke a previously authorized ingress rule for ``ip``."""
+ sg = self._resolve_sg_id(sg_id)
+ if from_port is None or to_port is None:
+ from_port, to_port = self._port_range(port)
- ec2 = boto3.client(
- "ec2",
- region_name=self._region,
- aws_access_key_id=key_id,
- aws_secret_access_key=secret,
- aws_session_token=token,
- )
+ if not self._boto3_available():
+ return self._unavailable("unblock_ip", ip)
+
+ key_id, secret, token = await self._get_credentials()
+ ec2 = self._ec2(key_id, secret, token)
cidr = f"{ip}/32"
+
try:
ec2.revoke_security_group_ingress(
- GroupId=self._sg_id,
+ GroupId=sg,
IpPermissions=[
{
"IpProtocol": protocol,
@@ -187,49 +237,39 @@ class AWSSGClient:
}
],
)
- logger.info("aws_sg.unblock_ip.success", sg=self._sg_id, cidr=cidr)
- return {"success": True, "action": "unblock_ip", "ip": ip, "sg_id": self._sg_id}
+ logger.info("aws_sg.unblock_ip.success", sg=sg, cidr=cidr)
+ return {
+ "success": True,
+ "action": "unblock_ip",
+ "ip": ip,
+ "sg_id": sg,
+ }
except ec2.exceptions.ClientError as exc:
code = exc.response["Error"]["Code"]
if code == "InvalidPermission.NotFound":
- return {"success": True, "action": "unblock_ip", "ip": ip, "note": "Rule not found (already removed)"}
+ return {
+ "success": True,
+ "action": "unblock_ip",
+ "ip": ip,
+ "sg_id": sg,
+ "note": "Rule not found (already removed)",
+ }
raise
- async def _httpx_authorize(
- self,
- key_id: str,
- secret: str,
- token: str | None,
- ip: str,
- protocol: str,
- from_port: int,
- to_port: int,
- action: str,
- ) -> dict[str, Any]:
- """Fallback: direct AWS EC2 API call without boto3.
- This is a placeholder; production use should install boto3."""
- logger.warning("aws_sg.httpx_fallback — boto3 unavailable, cannot execute live")
- return {
- "success": False,
- "action": action,
- "ip": ip,
- "note": "boto3 not installed in actions service — add boto3 to pyproject.toml",
- }
+ async def describe_rules(self, sg_id: str | None = None) -> list[dict[str, Any]]:
+ """List ingress rules on the target security group (empty when boto3 missing)."""
+ sg = self._resolve_sg_id(sg_id)
+ if not self._boto3_available():
+ return []
- async def describe_rules(self) -> list[dict[str, Any]]:
- """List ingress rules on the target security group."""
key_id, secret, token = await self._get_credentials()
- if not await self._boto3_available():
- return []
+ ec2 = self._ec2(key_id, secret, token)
+ resp = ec2.describe_security_group_rules(Filters=[{"Name": "group-id", "Values": [sg]}])
+ return resp.get("SecurityGroupRules", [])
- import boto3
- ec2 = boto3.client(
- "ec2",
- region_name=self._region,
- aws_access_key_id=key_id,
- aws_secret_access_key=secret,
- aws_session_token=token,
- )
- resp = ec2.describe_security_group_rules(Filters=[{"Name": "group-id", "Values": [self._sg_id]}])
- return resp.get("SecurityGroupRules", [])
+# Legacy alias: older code (and external plugins) may import the short name.
+AWSSGClient = AWSSecurityGroupsClient
+
+
+__all__ = ["AWSSecurityGroupsClient", "AWSSGClient"]
diff --git a/services/actions/tests/test_aws_security_groups_client.py b/services/actions/tests/test_aws_security_groups_client.py
new file mode 100644
index 000000000..6038c2107
--- /dev/null
+++ b/services/actions/tests/test_aws_security_groups_client.py
@@ -0,0 +1,189 @@
+"""Regression tests for the AWS Security Groups client wiring.
+
+These tests pin the public surface of ``app.clients.aws_security_groups`` so
+that the bug fixed in GH #82 cannot silently come back. The actions service
+fails to start at import time if any of the following regress:
+
+* ``AWSSecurityGroupsClient`` is removed or renamed (the network executor
+ imports it by that exact name).
+* The legacy ``AWSSGClient`` alias is dropped (older callers and external
+ plugins still import it).
+* The constructor stops accepting the keyword arguments that
+ ``app.executors.network`` passes (``access_key_id``, ``secret_access_key``,
+ ``region``, ``role_arn``, ``session_name``) or stops allowing a
+ ``region``-only construction for the rollback path.
+* ``block_ip`` / ``unblock_ip`` stop accepting the executor's
+ ``sg_id=`` / ``ip=`` / ``port=`` / ``protocol=`` keyword pattern.
+
+The tests intentionally avoid importing ``boto3``: in the absence of boto3
+the client must degrade to a structured "unavailable" stub instead of
+crashing, which keeps the actions container booting in minimal images.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+
+import pytest
+from app.clients.aws_security_groups import AWSSecurityGroupsClient, AWSSGClient
+
+
+def test_canonical_name_is_exported():
+ """The class the network executor imports must exist under this name."""
+ assert AWSSecurityGroupsClient.__name__ == "AWSSecurityGroupsClient"
+
+
+def test_legacy_alias_points_at_canonical_class():
+ """``AWSSGClient`` is kept as a backwards-compat alias and must not drift."""
+ assert AWSSGClient is AWSSecurityGroupsClient
+
+
+def test_constructor_accepts_executor_kwargs():
+ """Pin the kwargs ``app.executors.network._aws_client`` actually passes.
+
+ Reproduces the call site verbatim — if any of these are renamed or made
+ positional, instantiation in the executor breaks at runtime.
+ """
+ client = AWSSecurityGroupsClient(
+ access_key_id="AKIA-test",
+ secret_access_key="secret-test",
+ region="us-west-2",
+ role_arn="arn:aws:iam::123456789012:role/aisoc",
+ session_name="aisoc-action",
+ )
+ # Constructor must complete and stash the inputs without contacting AWS.
+ assert client._region == "us-west-2"
+ assert client._role_arn == "arn:aws:iam::123456789012:role/aisoc"
+
+
+def test_constructor_accepts_region_only_for_rollback_path():
+ """``BlockIPExecutor.rollback`` constructs the client with only a region.
+
+ That path must not require credentials (boto3's default credential chain
+ handles them in cluster), or the rollback after a successful block_ip
+ silently fails.
+ """
+ client = AWSSecurityGroupsClient(region="eu-west-1")
+ assert client._region == "eu-west-1"
+ assert client._access_key_id is None
+ assert client._secret_access_key is None
+
+
+def test_legacy_constructor_aliases_still_work():
+ """Older callers used ``assume_role_arn`` / ``sg_id`` keyword names.
+
+ Keep those accepted so external plugin code that imports the client
+ keeps working across the rename.
+ """
+ client = AWSSecurityGroupsClient(
+ region="us-east-1",
+ sg_id="sg-deadbeef",
+ assume_role_arn="arn:aws:iam::000000000000:role/legacy",
+ )
+ assert client._sg_id == "sg-deadbeef"
+ assert client._role_arn == "arn:aws:iam::000000000000:role/legacy"
+
+
+def test_block_ip_signature_matches_executor_call_site():
+ """The executor calls ``aws.block_ip(sg_id=..., ip=..., port=..., protocol=...)``.
+
+ All four parameter names must be accepted as keyword arguments. We
+ inspect the signature instead of calling AWS so the test runs offline.
+ """
+ sig = inspect.signature(AWSSecurityGroupsClient.block_ip)
+ params = sig.parameters
+ for kw in ("ip", "sg_id", "port", "protocol"):
+ assert kw in params, f"block_ip is missing required keyword: {kw}"
+
+
+def test_unblock_ip_signature_matches_executor_call_site():
+ """Same contract as block_ip — used by both AllowIPExecutor and rollback."""
+ sig = inspect.signature(AWSSecurityGroupsClient.unblock_ip)
+ params = sig.parameters
+ for kw in ("ip", "sg_id", "port", "protocol"):
+ assert kw in params, f"unblock_ip is missing required keyword: {kw}"
+
+
+def test_resolve_sg_id_requires_a_value():
+ """Calling block_ip / unblock_ip without an SG id at construct *or*
+ call time must raise — silently no-oping would be a security bug.
+ """
+ client = AWSSecurityGroupsClient(region="us-east-1")
+ with pytest.raises(ValueError, match="security_group_id is required"):
+ client._resolve_sg_id(None)
+
+
+def test_port_range_translation_is_aws_correct():
+ """``-1`` and ``None`` must collapse to ``(-1, -1)`` so the IpPermissions
+ block sent to ``authorize_security_group_ingress`` means "all ports"
+ rather than "port 0" or a malformed range.
+ """
+ assert AWSSecurityGroupsClient._port_range(-1) == (-1, -1)
+ assert AWSSecurityGroupsClient._port_range(None) == (-1, -1)
+ assert AWSSecurityGroupsClient._port_range(443) == (443, 443)
+
+
+def test_block_ip_returns_unavailable_stub_when_boto3_missing(monkeypatch):
+ """In a slim image without boto3 the actions service must still boot
+ and the executor must get a structured failure object back rather than
+ an ImportError. Pin that contract here.
+ """
+
+ monkeypatch.setattr(AWSSecurityGroupsClient, "_boto3_available", staticmethod(lambda: False))
+
+ client = AWSSecurityGroupsClient(region="us-east-1", security_group_id="sg-abc")
+ result = asyncio.run(client.block_ip("198.51.100.7"))
+
+ assert result["success"] is False
+ assert result["action"] == "block_ip"
+ assert result["ip"] == "198.51.100.7"
+ assert "boto3" in result["note"]
+
+
+def test_describe_rules_returns_empty_list_when_boto3_missing(monkeypatch):
+ """``describe_rules`` is read-only — when boto3 is missing it should
+ degrade to an empty list rather than crash, so callers can branch on
+ "no rules visible" instead of catching ImportError.
+ """
+
+ monkeypatch.setattr(AWSSecurityGroupsClient, "_boto3_available", staticmethod(lambda: False))
+
+ client = AWSSecurityGroupsClient(region="us-east-1", security_group_id="sg-abc")
+ rules = asyncio.run(client.describe_rules())
+ assert rules == []
+
+
+def test_executor_module_imports_cleanly():
+ """The original GH #82 symptom: ``from app.executors.network import ...``
+ raised ImportError because ``AWSSecurityGroupsClient`` did not exist.
+
+ This single import call is the cheapest possible regression check —
+ if it fails, the actions service won't start.
+ """
+ from app.executors.network import ( # noqa: F401
+ AllowIPExecutor,
+ BlockDomainExecutor,
+ BlockIPExecutor,
+ )
+
+
+def test_executor_registry_imports_cleanly():
+ """The actual import chain that crashed in production was
+
+ app.services.executor_registry
+ -> app.executors.network
+ -> app.clients.aws_security_groups (ImportError: AWSSecurityGroupsClient)
+
+ We only want to catch *this* regression, not unrelated import errors from
+ other dependencies that may not be installed in every environment, so we
+ skip cleanly on unrelated ImportError / ModuleNotFoundError and only
+ fail loudly if the failure mentions the AWS SG client.
+ """
+ try:
+ from app.services import executor_registry # noqa: F401
+ except (ImportError, ModuleNotFoundError) as exc:
+ msg = str(exc)
+ if "aws_security_groups" in msg or "AWSSecurityGroupsClient" in msg:
+ raise AssertionError(f"GH #82 regression: registry import broken by AWS SG client: {exc}") from exc
+ pytest.skip(f"unrelated dependency not available in this env: {exc}")
diff --git a/services/api/app/api/v1/endpoints/detection_proposals.py b/services/api/app/api/v1/endpoints/detection_proposals.py
index 6dfaa70bd..c78e7b7c2 100644
--- a/services/api/app/api/v1/endpoints/detection_proposals.py
+++ b/services/api/app/api/v1/endpoints/detection_proposals.py
@@ -49,18 +49,44 @@ from app.services.github import create_detection_pr
router = APIRouter(prefix="/detection-proposals", tags=["detection_rules", "dac"])
-# Repository root: services/api/app/api/v1/endpoints/detection_proposals.py
-# ^ ^ ^ ^ ^ ^ ^
-# parents: [0] [1] [2] [3] [4][5] [6] = repo root
+# Resolve the AiSOC repository root by walking up from this file until we
+# find the eval harness this module shells out to (``scripts/run_evals.py``).
+# Hard-coding ``Path(__file__).parents[6]`` only works on the host, where
+# this file sits six levels under the repo root. Inside the API Docker
+# image only the ``services/api/`` subtree is copied to ``/app``, so a
+# fixed parent index raises ``IndexError`` at import time and crashes the
+# entire API service before the first request — see GH #81 / #83.
#
-# On the host we sit six levels deep under the repo root. Inside the API
-# Docker image only the services/api/ subtree is copied to /app, so
-# parents[6] would IndexError. Resolve the deepest available ancestor and
-# let AISOC_REPO_ROOT override at runtime when the eval script is actually
-# needed (only relevant in dev/CI where the full repo is mounted).
+# Every code path that *uses* the resolved root re-checks
+# ``_EVAL_SCRIPT.exists()`` before invoking it, so the worst case in a
+# stripped image is a clean 500 from ``/run-eval`` (with a helpful message)
+# rather than an import-time crash.
+_REPO_ROOT_MARKER = ("scripts", "run_evals.py")
+
+
+def _resolve_repo_root(start: Path) -> Path:
+ """Walk up from ``start`` looking for ``scripts/run_evals.py``.
+
+ Returns the first ancestor that contains the marker file. If the marker
+ is not present (typical inside the slimmed API container), falls back
+ to the closest sensible ancestor — never to the filesystem root, which
+ would silently produce nonsense paths for subsequent ``/`` joins.
+ """
+ candidates = (start, *start.parents)
+ for candidate in candidates:
+ if (candidate.joinpath(*_REPO_ROOT_MARKER)).is_file():
+ return candidate
+ # Fallback: ``services/api`` (or its in-container equivalent ``/app``).
+ # That's parents[3] from this file and is guaranteed to exist in any
+ # environment where the API service can import this module.
+ parents = start.parents
+ if len(parents) > 3:
+ return parents[3]
+ return parents[-1] if parents else start
+
+
_ENDPOINT_FILE = Path(__file__).resolve()
-_ENDPOINT_PARENTS = list(_ENDPOINT_FILE.parents)
-_REPO_ROOT_DEFAULT = _ENDPOINT_PARENTS[6] if len(_ENDPOINT_PARENTS) > 6 else _ENDPOINT_PARENTS[-1]
+_REPO_ROOT_DEFAULT = _resolve_repo_root(_ENDPOINT_FILE)
_REPO_ROOT = Path(os.environ.get("AISOC_REPO_ROOT", str(_REPO_ROOT_DEFAULT)))
_EVAL_SCRIPT = _REPO_ROOT / "scripts" / "run_evals.py"
diff --git a/services/api/tests/api/v1/endpoints/test_detection_proposals_repo_root.py b/services/api/tests/api/v1/endpoints/test_detection_proposals_repo_root.py
new file mode 100644
index 000000000..d532140ba
--- /dev/null
+++ b/services/api/tests/api/v1/endpoints/test_detection_proposals_repo_root.py
@@ -0,0 +1,135 @@
+"""Regression tests for the repo-root resolver in ``detection_proposals``.
+
+This pins the fix for GH #81 / #83. The original bug was that the module
+computed its repo-root with ``Path(__file__).resolve().parents[6]``, which
+crashed at import time inside the slimmed API Docker image because only
+``services/api/`` is copied to ``/app`` (so ``parents[6]`` doesn't exist).
+
+The ``IndexError`` happened during ``app.api.v1.endpoints.detection_proposals``
+module import, so the entire FastAPI app failed to start — every endpoint
+(not just ``/run-eval``) returned 500. Tests below verify the marker-file
+resolver:
+
+1. Finds the real repo root on the host (where ``scripts/run_evals.py`` exists).
+2. Falls back gracefully when the marker is absent (Docker case) without
+ crashing and without resolving to ``/``.
+3. Honours the ``AISOC_REPO_ROOT`` environment override.
+4. Survives shallow path trees that would have triggered the original
+ ``IndexError``.
+"""
+
+from __future__ import annotations
+
+import importlib
+from pathlib import Path
+
+from app.api.v1.endpoints import detection_proposals as dp_endpoint
+
+
+def test_module_imports_without_indexerror():
+ """The whole point of the fix: importing the module must not raise.
+
+ If this test fails the API service won't boot.
+ """
+ # Simply re-importing exercises the module-level path resolution again.
+ importlib.reload(dp_endpoint)
+ assert hasattr(dp_endpoint, "_REPO_ROOT")
+ assert hasattr(dp_endpoint, "_EVAL_SCRIPT")
+
+
+def test_resolver_finds_root_via_marker_when_present(tmp_path: Path):
+ """When ``scripts/run_evals.py`` exists in some ancestor, that ancestor
+ is the chosen root — not a hard-coded parent index."""
+ repo = tmp_path / "fake-repo"
+ deep = repo / "services" / "api" / "app" / "api" / "v1" / "endpoints"
+ deep.mkdir(parents=True)
+ (repo / "scripts").mkdir()
+ (repo / "scripts" / "run_evals.py").write_text("# marker")
+
+ fake_module = deep / "detection_proposals.py"
+ fake_module.write_text("# stub")
+
+ resolved = dp_endpoint._resolve_repo_root(fake_module.resolve())
+ assert resolved == repo.resolve()
+
+
+def test_resolver_walks_up_through_many_levels(tmp_path: Path):
+ """The walk must traverse the full ancestor chain, not a fixed depth.
+
+ Use 10 nested directories to demonstrate this is not a parents[N] hack.
+ """
+ repo = tmp_path / "deep-repo"
+ deep = repo
+ for i in range(10):
+ deep = deep / f"level{i}"
+ deep.mkdir(parents=True)
+ (repo / "scripts").mkdir()
+ (repo / "scripts" / "run_evals.py").write_text("# marker")
+
+ leaf = deep / "detection_proposals.py"
+ leaf.write_text("# stub")
+
+ resolved = dp_endpoint._resolve_repo_root(leaf.resolve())
+ assert resolved == repo.resolve()
+
+
+def test_resolver_does_not_return_filesystem_root_when_marker_missing(
+ tmp_path: Path,
+):
+ """Reproduces the Docker case: no ``scripts/run_evals.py`` anywhere
+ above the file. The fallback must pick a sensible ancestor — *not*
+ ``/`` — because the resolved root is later joined with ``scripts/...``
+ and a ``/scripts/run_evals.py`` path would mask real bugs.
+ """
+ api_dir = tmp_path / "app"
+ deep = api_dir / "app" / "api" / "v1" / "endpoints"
+ deep.mkdir(parents=True)
+ fake_module = deep / "detection_proposals.py"
+ fake_module.write_text("# stub")
+
+ resolved = dp_endpoint._resolve_repo_root(fake_module.resolve())
+ # Must not be the filesystem root.
+ assert resolved != Path(resolved.anchor)
+ # Must be within tmp_path, i.e. a real ancestor of the start file.
+ assert tmp_path in resolved.parents or resolved == tmp_path or tmp_path == resolved
+
+
+def test_resolver_handles_extremely_shallow_paths(tmp_path: Path):
+ """Direct reproduction of the original GH #83 IndexError condition:
+ a file with fewer than 6 parents. The old ``parents[6]`` would raise
+ ``IndexError: tuple index out of range`` here. The new resolver must
+ return *some* path without raising.
+ """
+ shallow = tmp_path / "detection_proposals.py"
+ shallow.write_text("# stub")
+
+ # Must not raise — that's the whole regression.
+ resolved = dp_endpoint._resolve_repo_root(shallow.resolve())
+ assert isinstance(resolved, Path)
+
+
+def test_repo_root_honours_env_override(monkeypatch, tmp_path: Path):
+ """``AISOC_REPO_ROOT`` lets operators point at an explicit directory
+ inside Docker images that ship the ``scripts/`` tree alongside the API.
+ Reload the module so the env var is read at import time.
+ """
+ custom = tmp_path / "custom-root"
+ (custom / "scripts").mkdir(parents=True)
+ (custom / "scripts" / "run_evals.py").write_text("# marker")
+
+ monkeypatch.setenv("AISOC_REPO_ROOT", str(custom))
+ reloaded = importlib.reload(dp_endpoint)
+
+ assert reloaded._REPO_ROOT == custom
+ assert reloaded._EVAL_SCRIPT == custom / "scripts" / "run_evals.py"
+
+
+def test_eval_script_path_is_under_resolved_root():
+ """The derived ``_EVAL_SCRIPT`` must always be ``<root>/scripts/run_evals.py``.
+
+ This guards against future refactors silently moving the script path.
+ """
+ importlib.reload(dp_endpoint)
+ assert dp_endpoint._EVAL_SCRIPT.name == "run_evals.py"
+ assert dp_endpoint._EVAL_SCRIPT.parent.name == "scripts"
+ assert dp_endpoint._EVAL_SCRIPT.parent.parent == dp_endpoint._REPO_ROOT