aisoc-cli 0.1.0__py3-none-any.whl

aisoc_cli/templates/connector/README.md.tmpl

@@ -0,0 +1,37 @@
+# $name
+
+AiSOC **connector** plugin generated by `aisoc plugin new`.
+
+## Where this lives
+
+Connectors are run by `services/connectors`. To wire this up locally, drop the
+class into `services/connectors/app/connectors/$slug.py` and add it to the
+`_CONNECTOR_CLASSES` registry in `services/connectors/app/connectors/__init__.py`
+(see `AGENTS.md` → "Connector platform conventions").
+
+## Severity ladder
+
+The AiSOC severity ladder is exactly four tiers:
+
+```
+info | low | medium | high
+```
+
+Every vendor-native ladder must collapse into this set inside `normalize()`.
+Fill out the `SEVERITY_MAP` dict in `connector.py`.
+
+## Develop
+
+```bash
+aisoc plugin validate plugin.yaml
+pytest -v   # add tests under tests/test_${slug}_connector.py
+```
+
+## Publish
+
+```bash
+aisoc plugin publish .
+```
+
+See [apps/docs/docs/connectors](https://github.com/beenuar/AiSOC/tree/main/apps/docs/docs/connectors)
+for the per-connector setup walkthrough format.

aisoc_cli/templates/connector/connector.py.tmpl

@@ -0,0 +1,106 @@
+"""
+$name — AiSOC connector plugin.
+
+Connectors are owned by ``services/connectors``. They subclass ``BaseConnector``
+and implement three async methods:
+
+- ``test_connection()`` — quick health check used by the UI "Test" button.
+- ``fetch_alerts()``    — pull a batch of upstream records on each poll tick.
+- ``normalize()``       — map vendor records onto the AiSOC OCSF-aligned schema.
+
+The in-process ``ConnectorScheduler`` will instantiate this class once per
+enabled tenant instance and call ``fetch_alerts`` on the configured cadence.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+# When this plugin lives inside the AiSOC monorepo, prefer the real base class:
+#   from services.connectors.app.connectors.base import BaseConnector, ConnectorSchema
+# The shim below lets the scaffold lint cleanly outside the monorepo.
+try:  # pragma: no cover
+    from services.connectors.app.connectors.base import BaseConnector, ConnectorSchema
+except Exception:  # pragma: no cover
+    BaseConnector = object  # type: ignore[misc,assignment]
+    ConnectorSchema = dict  # type: ignore[misc,assignment]
+
+
+SEVERITY_MAP: dict[str, str] = {
+    # Map vendor-native severities onto AiSOC's four-tier ladder.
+    # info | low | medium | high
+}
+
+
+class Connector(BaseConnector):  # type: ignore[misc]
+    """$name connector."""
+
+    connector_id = "$slug"
+
+    @classmethod
+    def schema(cls) -> ConnectorSchema:  # type: ignore[override]
+        # Mirrors plugin.yaml.config_schema. Kept as a classmethod so the API
+        # service can describe this connector without instantiating it.
+        return ConnectorSchema(  # type: ignore[call-arg]
+            name="$slug",
+            label="$name",
+            description="$name connector",
+            category="siem",  # edr | siem | cloud | iam | saas | vcs | network
+            fields=[],
+            oauth=None,
+            default_poll_interval_seconds=300,
+        )
+
+    def __init__(self, instance_id: str, tenant_id: str, config: dict[str, Any]) -> None:
+        super().__init__(instance_id=instance_id, tenant_id=tenant_id, config=config)
+        self.base_url: str = config["base_url"].rstrip("/")
+        self.api_key: str | None = config.get("api_key")
+        self.verify_tls: bool = bool(config.get("verify_tls", True))
+        self.page_size: int = int(config.get("page_size", 100))
+
+    def _client(self) -> httpx.AsyncClient:
+        headers = {"Accept": "application/json"}
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        return httpx.AsyncClient(
+            base_url=self.base_url,
+            headers=headers,
+            verify=self.verify_tls,
+            timeout=httpx.Timeout(15.0, connect=5.0),
+        )
+
+    async def test_connection(self) -> dict[str, Any]:
+        """Quick reachability + auth check."""
+        async with self._client() as client:
+            resp = await client.get("/health")
+            resp.raise_for_status()
+            return {"ok": True, "status": resp.status_code}
+
+    async def fetch_alerts(self, since_iso: str | None = None) -> list[dict[str, Any]]:
+        """Pull a batch of vendor records.
+
+        The scheduler hands us the high-watermark from the last successful tick
+        as ``since_iso``. Use it to ask the upstream for "everything newer than".
+        """
+        params: dict[str, Any] = {"limit": self.page_size}
+        if since_iso:
+            params["since"] = since_iso
+
+        async with self._client() as client:
+            resp = await client.get("/alerts", params=params)
+            resp.raise_for_status()
+            data = resp.json()
+            return list(data.get("results", []))
+
+    def normalize(self, raw: dict[str, Any]) -> dict[str, Any]:
+        """Map a vendor record onto the AiSOC OCSF-aligned event shape."""
+        return {
+            "source": "$slug",
+            "vendor_id": str(raw.get("id", "")),
+            "timestamp": raw.get("timestamp"),
+            "title": raw.get("title", ""),
+            "description": raw.get("description", ""),
+            "severity": SEVERITY_MAP.get(str(raw.get("severity", "")).lower(), "info"),
+            "raw": raw,
+        }

aisoc_cli/templates/connector/plugin.yaml.tmpl

@@ -0,0 +1,42 @@
+id: $slug
+name: $name
+version: 0.1.0
+plugin_type: connector
+tier: community
+description: >
+  $name pulls alerts/events from an upstream source and normalizes them
+  onto the AiSOC OCSF-aligned schema with the four-tier severity ladder
+  (info | low | medium | high).
+author: "$author"
+tags: [connector]
+license: MIT
+min_aisoc_version: "4.0.0"
+runtime: python
+entry_point: connector.py
+config_schema:
+  type: object
+  required: [base_url]
+  properties:
+    base_url:
+      type: string
+      description: "Upstream API base URL, e.g. https://api.example.com"
+    api_key:
+      type: string
+      description: "API key / bearer token. Stored encrypted in the credential vault."
+      secret: true
+    poll_interval_seconds:
+      type: integer
+      description: "How often the in-process scheduler should poll. Default 300s."
+      default: 300
+      minimum: 30
+      maximum: 3600
+    verify_tls:
+      type: boolean
+      description: "Verify TLS certs on the upstream. Disable only for dev."
+      default: true
+    page_size:
+      type: integer
+      description: "Records per upstream API page."
+      default: 100
+      minimum: 1
+      maximum: 10000

aisoc_cli/templates/detection/README.md.tmpl

@@ -0,0 +1,30 @@
+# $name
+
+AiSOC **detection** plugin generated by `aisoc plugin new`.
+
+## Layout
+
+```
+$slug/
+├── plugin.yaml
+├── README.md
+└── rules/
+    └── example.yaml   # add one YAML file per rule
+```
+
+Detection rules use the AiSOC schema (severity ladder is exactly
+`info | low | medium | high`). See `detections/` in the AiSOC monorepo for
+working examples across endpoint, network, cloud, identity, and application.
+
+## Develop
+
+```bash
+aisoc plugin validate plugin.yaml
+aisoc detection validate rules/example.yaml
+```
+
+## Publish
+
+```bash
+aisoc plugin publish .
+```

aisoc_cli/templates/detection/plugin.yaml.tmpl

@@ -0,0 +1,17 @@
+id: $slug
+name: $name
+version: 0.1.0
+plugin_type: detection
+tier: community
+description: >
+  $name ships one or more AiSOC detection rules. Each rule lives in
+  ``rules/*.yaml`` and is validated by ``aisoc detection validate``.
+author: "$author"
+tags: [detection]
+license: MIT
+min_aisoc_version: "4.0.0"
+runtime: python
+entry_point: rules/
+config_schema:
+  type: object
+  properties: {}

aisoc_cli/templates/detection/rules/example.yaml.tmpl

@@ -0,0 +1,28 @@
+id: det-$slug-001
+name: Example detection from $name
+description: >
+  Replace this with a one-paragraph description of what this rule fires on,
+  why it matters, and which adversary behaviour it covers.
+version: 1.0.0
+severity: medium    # info | low | medium | high
+tags:
+  - mitre.attack.t0000
+  - tlp.white
+category: endpoint  # endpoint | network | cloud | identity | application
+log_source:
+  product: example
+  service: example
+detection:
+  condition: |
+    # TODO: replace with a real boolean expression over normalized event fields.
+    event.action == "example_action"
+    AND event.outcome == "success"
+false_positives:
+  - List the realistic noise sources here so analysts know how to tune.
+playbook: tpl-investigation
+enabled: true
+author: "$author"
+references:
+  - https://attack.mitre.org/
+created: '2026-01-01'
+modified: '2026-01-01'

aisoc_cli/templates/enricher/README.md.tmpl

@@ -0,0 +1,29 @@
+# $name
+
+AiSOC **enricher** plugin generated by `aisoc plugin new`.
+
+Enrichers add context to in-flight events. They are called by the orchestrator
+once per matching event and must:
+
+- Be fast (sub-second). Set `timeout_seconds` low.
+- Be side-effect-free.
+- Never raise on a miss — return `{}` instead.
+
+## Develop
+
+```bash
+# Validate the manifest
+aisoc plugin validate plugin.yaml
+
+# Run unit tests once you add them
+pytest -v
+```
+
+## Publish
+
+```bash
+aisoc plugin publish .
+```
+
+See the [AiSOC plugin docs](https://github.com/beenuar/AiSOC/tree/main/apps/docs/docs/plugins)
+for the full lifecycle.

aisoc_cli/templates/enricher/plugin.py.tmpl

@@ -0,0 +1,42 @@
+"""
+$name — AiSOC enricher plugin.
+
+Enrichers receive a normalized event payload and return a small dict of
+additional context to merge back into the event. They run on the hot path
+inside the orchestrator graph, so keep them fast and side-effect-free.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+
+class Plugin:
+    """Main plugin class — AiSOC instantiates this once per tenant per worker
+    and calls ``run()`` once per matching event.
+    """
+
+    def __init__(self, config: dict[str, Any]) -> None:
+        self.config = config
+        self.api_key: str | None = config.get("api_key")
+        self.timeout_seconds: int = int(config.get("timeout_seconds", 5))
+
+    async def run(
+        self,
+        payload: dict[str, Any],
+        context: dict[str, Any],
+    ) -> dict[str, Any]:
+        """Enrich the alert/event payload.
+
+        Args:
+            payload: Normalized event in OCSF-aligned shape.
+            context: Runtime context — ``tenant_id``, ``trace_id``, etc.
+
+        Returns:
+            Dict to merge into ``payload["enrichments"]["$slug"]``. Return an
+            empty dict if you have nothing to add — never raise on misses.
+        """
+        # TODO: replace with your enrichment lookup.
+        return {
+            "enriched_by": "$slug",
+            "data": {},
+        }

aisoc_cli/templates/enricher/plugin.yaml.tmpl

@@ -0,0 +1,29 @@
+id: $slug
+name: $name
+version: 0.1.0
+plugin_type: enricher
+tier: community
+description: >
+  $name enriches alerts and events with additional context — IoC reputation,
+  asset metadata, user attributes, geolocation, etc. AiSOC calls run() once
+  per matching event in the orchestrator pipeline.
+author: "$author"
+tags: [enricher]
+license: MIT
+min_aisoc_version: "4.0.0"
+runtime: python
+entry_point: plugin.py
+config_schema:
+  type: object
+  required: []
+  properties:
+    api_key:
+      type: string
+      description: "API key for the upstream enrichment service."
+      secret: true
+    timeout_seconds:
+      type: integer
+      description: "Per-request timeout. Keep low — enrichers run on the hot path."
+      default: 5
+      minimum: 1
+      maximum: 30

aisoc_cli/templates/responder/README.md.tmpl

@@ -0,0 +1,25 @@
+# $name
+
+AiSOC **responder** plugin generated by `aisoc plugin new`.
+
+## Contract
+
+- `supported_actions` — list of verbs your responder understands.
+- `execute(action, params, context)` — returns
+  `{"status": "ok" | "skipped" | "error", "detail": ..., "artifact": ...}`.
+
+Always honour `dry_run=true` and return `status="skipped"`. The investigation
+timeline relies on this to render an honest record of what was actually done.
+
+## Develop
+
+```bash
+aisoc plugin validate plugin.yaml
+pytest -v
+```
+
+## Publish
+
+```bash
+aisoc plugin publish .
+```

aisoc_cli/templates/responder/plugin.py.tmpl

@@ -0,0 +1,66 @@
+"""
+$name — AiSOC responder plugin.
+
+Responders execute containment / remediation actions. A playbook step calls
+``Plugin.execute(action, params, context)`` and expects a structured result
+back so the timeline can render what happened.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+
+class Plugin:
+    """Main plugin class. AiSOC instantiates one per tenant per worker."""
+
+    def __init__(self, config: dict[str, Any]) -> None:
+        self.config = config
+        self.api_key: str | None = config.get("api_key")
+        self.dry_run: bool = bool(config.get("dry_run", False))
+        self.timeout_seconds: int = int(config.get("timeout_seconds", 15))
+
+    @property
+    def supported_actions(self) -> list[str]:
+        """Action names this responder knows how to run."""
+        # TODO: list the verbs your responder supports, e.g. ["disable_user",
+        # "isolate_host", "block_ip"]. The orchestrator validates against this.
+        return []
+
+    async def execute(
+        self,
+        action: str,
+        params: dict[str, Any],
+        context: dict[str, Any],
+    ) -> dict[str, Any]:
+        """Run a single action.
+
+        Args:
+            action: Verb chosen by the playbook (one of ``supported_actions``).
+            params: Action-specific arguments (target user, host, IP, etc.).
+            context: Runtime context — ``tenant_id``, ``trace_id``, ``case_id``.
+
+        Returns:
+            ``{"status": "ok" | "skipped" | "error", "detail": ..., "artifact": ...}``
+
+            ``status="skipped"`` should be used in dry-run mode so the timeline
+            stays honest about what really happened.
+        """
+        if action not in self.supported_actions:
+            return {
+                "status": "error",
+                "detail": f"Unsupported action: {action}",
+            }
+
+        if self.dry_run:
+            return {
+                "status": "skipped",
+                "detail": "dry_run=true",
+                "artifact": {"action": action, "params": params},
+            }
+
+        # TODO: implement the real call to the upstream control plane.
+        return {
+            "status": "ok",
+            "detail": f"$slug executed {action}",
+            "artifact": {"action": action, "params": params},
+        }

aisoc_cli/templates/responder/plugin.yaml.tmpl

@@ -0,0 +1,32 @@
+id: $slug
+name: $name
+version: 0.1.0
+plugin_type: responder
+tier: community
+description: >
+  $name takes a containment / remediation action when fired by a playbook.
+  Examples: disable a user, isolate an endpoint, block an IP at the edge.
+author: "$author"
+tags: [responder]
+license: MIT
+min_aisoc_version: "4.0.0"
+runtime: python
+entry_point: plugin.py
+config_schema:
+  type: object
+  required: []
+  properties:
+    api_key:
+      type: string
+      description: "API token used to call the upstream control plane."
+      secret: true
+    dry_run:
+      type: boolean
+      description: "If true, log the intended action without executing it."
+      default: false
+    timeout_seconds:
+      type: integer
+      description: "Per-action timeout."
+      default: 15
+      minimum: 1
+      maximum: 120

aisoc_cli/templates/widget/README.md.tmpl

@@ -0,0 +1,40 @@
+# $name
+
+AiSOC **widget** plugin generated by `aisoc plugin new`.
+
+## Contract
+
+`Widget.fetch_data(context)` returns a dict shaped like:
+
+```json
+{
+  "type": "kpi",
+  "title": "string",
+  "data": { "value": 0, "label": "events" },
+  "refresh_interval_seconds": 60
+}
+```
+
+`type` is one of:
+
+| type         | `data` shape                                  | renders as              |
+| ------------ | --------------------------------------------- | ----------------------- |
+| `kpi`        | `{"value": number, "label": str}`             | big-number card         |
+| `timeseries` | `[{"t": iso8601, "v": number}, ...]`          | line chart              |
+| `table`      | `{"columns": [str], "rows": [[Any]]}`         | dense table             |
+| `list`       | `[{"primary": str, "secondary": str}, ...]`   | top-N list              |
+
+Keep `fetch_data()` fast — widgets are polled on every dashboard tick.
+
+## Develop
+
+```bash
+aisoc plugin validate plugin.yaml
+pytest -v
+```
+
+## Publish
+
+```bash
+aisoc plugin publish .
+```

aisoc_cli/templates/widget/plugin.yaml.tmpl

@@ -0,0 +1,29 @@
+id: $slug
+name: $name
+version: 0.1.0
+plugin_type: widget
+tier: community
+description: >
+  $name is a custom dashboard widget for AiSOC. The widget is rendered inside
+  the saved-views / dashboard surface and receives a small query API plus the
+  current tenant's theme tokens.
+author: "$author"
+tags: [widget]
+license: MIT
+min_aisoc_version: "4.0.0"
+runtime: python
+entry_point: widget.py
+config_schema:
+  type: object
+  required: []
+  properties:
+    title:
+      type: string
+      description: "Display title shown in the widget header."
+      default: "$name"
+    refresh_interval_seconds:
+      type: integer
+      description: "How often the dashboard should re-fetch the widget's data."
+      default: 60
+      minimum: 5
+      maximum: 3600

aisoc_cli/templates/widget/widget.py.tmpl

@@ -0,0 +1,50 @@
+"""
+$name — AiSOC dashboard widget plugin.
+
+Widgets are rendered inside the AiSOC dashboard / saved-views surface. The
+backend ``Widget.fetch_data()`` call returns a small typed payload that the
+frontend renderer turns into a card, chart, or table.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+
+class Widget:
+    """Main widget class — AiSOC instantiates one per dashboard placement."""
+
+    widget_id = "$slug"
+
+    def __init__(self, config: dict[str, Any]) -> None:
+        self.config = config
+        self.title: str = str(config.get("title", "$name"))
+        self.refresh_interval_seconds: int = int(
+            config.get("refresh_interval_seconds", 60)
+        )
+
+    async def fetch_data(self, context: dict[str, Any]) -> dict[str, Any]:
+        """Return the data payload the dashboard should render.
+
+        Args:
+            context: Runtime context — ``tenant_id``, ``user_id``, ``time_range``.
+
+        Returns:
+            A dict with the shape::
+
+                {
+                    "type": "kpi" | "timeseries" | "table" | "list",
+                    "title": str,
+                    "data": Any,        # type-specific payload
+                    "refresh_interval_seconds": int,
+                }
+
+            ``data`` is widget-type-specific. KPI widgets return a single number,
+            timeseries return ``[{"t": iso8601, "v": number}, ...]``, etc.
+        """
+        # TODO: query the AiSOC API or directly run the widget's data source.
+        return {
+            "type": "kpi",
+            "title": self.title,
+            "data": {"value": 0, "label": "events"},
+            "refresh_interval_seconds": self.refresh_interval_seconds,
+        }