feat(connector-linter): add VC1xx config and VC2xx metadata checks

Author: jabesq

shared/connector_linter/connector_linter/checks/vc1xx_config/__init__.py

@@ -0,0 +1,11 @@
+"""VC1xx — Configuration checks.
+
+Validates connector configuration files (docker-compose.yml, .env.sample,
+config.yml.sample) for compliance with OpenCTI conventions.
+
+VC101  config-token-default        OPENCTI_TOKEN must default to ChangeMe
+VC102  config-url-default          OPENCTI_URL must default to http://localhost
+VC103  config-variable-prefix      Env vars must use OPENCTI_, CONNECTOR_, or <NAME>_ prefix
+VC104  config-file-samples         config.yml.sample + docker-compose/env must exist
+VC105  no-absolute-import-date     Import dates must use ISO duration, not absolute dates
+"""

shared/connector_linter/connector_linter/checks/vc1xx_config/_helpers.py

@@ -0,0 +1,205 @@
+"""Helpers for configuration-file parsing.
+
+Extracts environment variables from ``docker-compose.yml`` and
+``.env.sample`` files, including commented-out lines.  Also locates
+``config.yml.sample`` and scans for ``ChangeMe`` placeholder values.
+"""
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+from connector_linter.models import ConnectorContext
+
+
+@dataclass
+class EnvVar:
+    """A parsed environment variable."""
+
+    name: str
+    value: str
+    line: int
+    file_path: Path
+    is_commented: bool
+
+
+# ---------------------------------------------------------------------------
+# Regex: docker-compose.yml environment lines
+#
+# Matches lines like:
+#     - OPENCTI_URL=http://localhost       (uncommented)
+#   #   - OPENCTI_URL=http://localhost     (commented out)
+#
+# Capture groups:
+#   commented — leading "#" (present when the line is commented out)
+#   name      — uppercase env var name (e.g. OPENCTI_TOKEN)
+#   value     — everything after "=" up to an optional inline comment
+#
+# Trailing inline comments (# …) are stripped from the value.
+# ---------------------------------------------------------------------------
+_COMPOSE_ENV_RE = re.compile(
+    r"^(?P<commented>\s*#)?\s*-\s*(?P<name>[A-Z][A-Z0-9_]*)=(?P<value>[^#\n]*?)(?:\s*#.*)?\s*$",
+)
+
+# ---------------------------------------------------------------------------
+# Regex: .env.sample (dotenv-style) lines
+#
+# Matches lines like:
+#   OPENCTI_TOKEN=ChangeMe               (uncommented)
+#   # OPENCTI_TOKEN=ChangeMe             (commented out)
+#
+# Same capture groups as _COMPOSE_ENV_RE (commented, name, value).
+# The difference is the absence of the YAML list marker "- ".
+# ---------------------------------------------------------------------------
+_DOTENV_RE = re.compile(
+    r"^(?P<commented>\s*#)?\s*(?P<name>[A-Z][A-Z0-9_]*)=(?P<value>[^#\n]*?)(?:\s*#.*)?\s*$",
+)
+
+
+def _parse_lines(
+    file_path: Path,
+    lines: list[str],
+    pattern: re.Pattern[str],
+) -> list[EnvVar]:
+    """Extract EnvVar entries from raw lines.
+
+    Iterates line-by-line, applying the given regex ``pattern`` to each line.
+    Both commented and uncommented matches are captured — the ``is_commented``
+    flag lets callers decide which to keep or skip.
+    """
+    results: list[EnvVar] = []
+    for line_no, line in enumerate(lines, 1):
+        m = pattern.match(line)
+        if m:
+            results.append(
+                EnvVar(
+                    name=m.group("name"),
+                    value=m.group("value").strip(),
+                    line=line_no,
+                    file_path=file_path,
+                    is_commented=bool(m.group("commented")),
+                ),
+            )
+    return results
+
+
+def extract_env_vars_from_docker_compose(ctx: ConnectorContext) -> list[EnvVar]:
+    """Extract environment variables from docker-compose.yml."""
+    compose_path = ctx.path / "docker-compose.yml"
+    if not compose_path.is_file():
+        return []
+    with compose_path.open(encoding="utf-8") as f:
+        return _parse_lines(compose_path, f.readlines(), _COMPOSE_ENV_RE)
+
+
+def extract_env_vars_from_env_sample(ctx: ConnectorContext) -> list[EnvVar]:
+    """Extract environment variables from .env.sample."""
+    env_path = ctx.path / ".env.sample"
+    if not env_path.is_file():
+        return []
+    with env_path.open(encoding="utf-8") as f:
+        return _parse_lines(env_path, f.readlines(), _DOTENV_RE)
+
+
+def extract_all_env_vars(ctx: ConnectorContext) -> list[EnvVar]:
+    """Extract env vars from docker-compose.yml and .env.sample."""
+    return extract_env_vars_from_docker_compose(ctx) + extract_env_vars_from_env_sample(
+        ctx,
+    )
+
+
+def derive_connector_prefixes(ctx: ConnectorContext) -> list[str]:
+    """Derive valid connector-specific prefixes from the directory name.
+
+    Examples:
+      ``mandiant``         → ``["MANDIANT"]``
+      ``abuse-ssl``        → ``["ABUSE_SSL", "ABUSESSL"]``
+      ``recorded-future``  → ``["RECORDED_FUTURE", "RECORDEDFUTURE"]``
+
+    """
+    dirname = ctx.path.name
+    prefixes: set[str] = set()
+    # Hyphen → underscore:  "abuse-ssl" → "ABUSE_SSL"
+    prefixes.add(dirname.upper().replace("-", "_"))
+    # Hyphen removed:       "abuse-ssl" → "ABUSESSL"
+    # (Some legacy connectors use this convention.)
+    prefixes.add(dirname.upper().replace("-", ""))
+    return sorted(prefixes)
+
+
+def find_config_yml_sample(ctx: ConnectorContext) -> Path | None:
+    """Locate config.yml.sample (root or src/)."""
+    candidates = [
+        ctx.path / "config.yml.sample",
+        ctx.path / "src" / "config.yml.sample",
+    ]
+    for path in candidates:
+        if path.is_file():
+            return path
+    return None
+
+
+def has_docker_compose_env(ctx: ConnectorContext) -> bool:
+    """Return True if docker-compose.yml exists with environment variables."""
+    return bool(extract_env_vars_from_docker_compose(ctx))
+
+
+def has_env_sample(ctx: ConnectorContext) -> bool:
+    """Return True if .env.sample exists."""
+    return (ctx.path / ".env.sample").is_file()
+
+
+@dataclass
+class ChangeMeHit:
+    """A ChangeMe value found in a config file with wrong case."""
+
+    file_path: Path
+    line: int
+    raw_value: str
+
+
+# ---------------------------------------------------------------------------
+# Regex: case-insensitive "ChangeMe" placeholder detector
+#
+# Matches the word "ChangeMe" regardless of case (CHANGEME, changeme, etc.)
+# appearing as a YAML value (after ":") or env value (after "="):
+#   OPENCTI_TOKEN=changeme         → matches "changeme"
+#   token: 'CHANGEME'              → matches "CHANGEME"
+#
+# Optional surrounding quotes (' or ") and trailing inline comments are
+# tolerated but not captured.
+# ---------------------------------------------------------------------------
+_CHANGEME_LINE_RE = re.compile(
+    r"(?:^|[=:]\s*['\"]?)(?P<value>change\s*me)['\"]?\s*(?:#.*)?$",
+    re.MULTILINE | re.IGNORECASE,
+)
+
+
+def find_bad_changeme_values(file_path: Path) -> list[ChangeMeHit]:
+    """Find ChangeMe values with wrong case in any config file.
+
+    A "bad" value is any case variant of ChangeMe that is *not* the
+    canonical form ``ChangeMe`` (e.g. ``CHANGEME``, ``changeme``).
+
+    Commented lines (starting with ``#``) are skipped because they are
+    inactive — fixing their case would be noise, and some commented lines
+    may intentionally use a different casing as documentation.
+    """
+    if not file_path.is_file():
+        return []
+    with file_path.open(encoding="utf-8") as f:
+        lines = f.readlines()
+
+    hits: list[ChangeMeHit] = []
+    for line_no, line in enumerate(lines, 1):
+        # Skip fully commented lines — only active values matter for casing
+        stripped = line.lstrip()
+        if stripped.startswith("#"):
+            continue
+        m = _CHANGEME_LINE_RE.search(line)
+        if m:
+            raw = m.group("value").strip()
+            # Only flag if casing does not match the canonical "ChangeMe"
+            if raw != "ChangeMe":
+                hits.append(ChangeMeHit(file_path, line_no, raw))
+    return hits

shared/connector_linter/connector_linter/checks/vc1xx_config/vc101_config_token.py

@@ -0,0 +1,130 @@
+"""VC101 — OPENCTI_TOKEN must default to ``ChangeMe``.
+
+Following the January 2026 alignment commit, all configuration files
+must use exactly ``ChangeMe`` as the placeholder value for
+``OPENCTI_TOKEN`` (not ``CHANGEME``, ``changeme``, or a real token).
+
+Environment-variable references like ``${OPENCTI_TOKEN}`` are acceptable.
+
+Scope: Common (all connector types).
+"""
+
+from connector_linter.checks.vc1xx_config._helpers import extract_all_env_vars
+from connector_linter.models import CheckFinding, ConnectorContext, Severity
+from connector_linter.registry import CheckRegistry
+
+_VALID_PLACEHOLDER = "ChangeMe"
+
+
+@CheckRegistry.register(
+    code="VC101",
+    name="config-token-default",
+    description="OPENCTI_TOKEN must default to ChangeMe",
+    severity=Severity.ERROR,
+)
+def check_config_token(ctx: ConnectorContext) -> list[CheckFinding]:
+    """Check OPENCTI_TOKEN placeholder value in configuration files."""
+    # Step 1: Gather all env vars from docker-compose.yml and .env.sample
+    all_vars = extract_all_env_vars(ctx)
+
+    if not all_vars:
+        return [
+            CheckFinding(
+                message="No configuration file found (docker-compose.yml or .env.sample)",
+                passed=False,
+                suggestion="Add a docker-compose.yml with environment variables.",
+            ),
+        ]
+
+    # Step 2: Keep only uncommented OPENCTI_TOKEN entries.
+    # Commented-out lines are informational — only active values matter.
+    token_vars = [
+        v for v in all_vars if v.name == "OPENCTI_TOKEN" and not v.is_commented
+    ]
+
+    if not token_vars:
+        return [
+            CheckFinding(
+                message="OPENCTI_TOKEN not found in configuration files",
+                passed=False,
+                suggestion="Add OPENCTI_TOKEN=ChangeMe to docker-compose.yml.",
+            ),
+        ]
+
+    # Step 3: Validate each OPENCTI_TOKEN occurrence.
+    #
+    # Decision tree for each value:
+    #   ${...}      → PASS  (env reference — delegated to runtime)
+    #   ChangeMe    → PASS  (canonical placeholder, exact case)
+    #   changeme/*  → FAIL  (wrong case — must match Jan 2026 alignment)
+    #   (empty)     → FAIL  (must have a placeholder)
+    #   anything    → FAIL  (likely a real token committed by mistake)
+    results: list[CheckFinding] = []
+    for var in token_vars:
+        value = var.value
+
+        # ---------------------------------------------------------------------------
+        # Environment variable reference — e.g. ${OPENCTI_TOKEN}
+        #
+        # docker-compose files often delegate to the host environment via
+        # ${VAR} syntax.  This is perfectly fine — the actual secret is
+        # never stored in the repo.
+        # ---------------------------------------------------------------------------
+        if value.startswith("${") and value.endswith("}"):
+            results.append(
+                CheckFinding(
+                    message=f"OPENCTI_TOKEN uses env reference ({value})",
+                    passed=True,
+                    file_path=var.file_path,
+                    line=var.line,
+                ),
+            )
+            continue
+
+        if value == _VALID_PLACEHOLDER:
+            results.append(
+                CheckFinding(
+                    message="OPENCTI_TOKEN=ChangeMe ✓",
+                    passed=True,
+                    file_path=var.file_path,
+                    line=var.line,
+                ),
+            )
+        elif value.lower() == "changeme":
+            # Case mismatch — the Jan 2026 alignment mandates exact "ChangeMe"
+            results.append(
+                CheckFinding(
+                    message=f"OPENCTI_TOKEN={value} — wrong case",
+                    passed=False,
+                    file_path=var.file_path,
+                    line=var.line,
+                    suggestion=f"Change from '{value}' to 'ChangeMe' (exact case).",
+                ),
+            )
+        elif not value:
+            results.append(
+                CheckFinding(
+                    message="OPENCTI_TOKEN has empty value",
+                    passed=False,
+                    file_path=var.file_path,
+                    line=var.line,
+                    suggestion="Set OPENCTI_TOKEN=ChangeMe as the placeholder value.",
+                ),
+            )
+        else:
+            # Non-standard value — could be a real token accidentally committed.
+            # Truncate to 20 chars to avoid leaking secrets in the output.
+            results.append(
+                CheckFinding(
+                    message=f"OPENCTI_TOKEN has non-standard value: {value[:20]}{'...' if len(value) > 20 else ''}",
+                    passed=False,
+                    file_path=var.file_path,
+                    line=var.line,
+                    suggestion=(
+                        "Use 'ChangeMe' as the placeholder value. "
+                        "Never commit real tokens."
+                    ),
+                ),
+            )
+
+    return results