validate.py: flag references to undeclared WorkflowCustomVariables (#42)

* validate.py: flag references to undeclared WorkflowCustomVariables

A workflow that references ${data['WorkflowCustomVariable.<name>']} for a variable
that no CreateVariable (or UpdateVariable setter) declares imports and api_validates
cleanly, then fails only at release with 'property "..." contains unknown variable
"WorkflowCustomVariable.<name>"'. Preflight never caught it because the validator
never collected declared variable names.

Add _validate_custom_variable_refs to the structural tier: collect declared names from
CreateVariable variable_schema properties and WorkflowCustomVariable setter blocks
(recursing into loops), scan the raw file for WorkflowCustomVariable.<name> references,
and flag any name that is not declared. Reinforce the rule in the authoring and
workflows yaml-schema references, and add tests covering the undeclared case, both
declaration mechanisms, and de-duplication. Correct three existing fixtures that
referenced custom variables they never declared.

* pylintrc: raise max-module-lines to 1400 for the new validate.py guard

validate.py crossed the 1350 line limit (now 1377) with the undefined-custom-variable
check. Consistent with prior guard additions (1200 -> 1300 -> 1350), bump to 1400.

Author: mraible

.pylintrc

@@ -337,7 +337,7 @@ max-line-length=127
 # with many per-trigger/per-class rules); it has grown past the 1000 default as
 # rules were added. Kept as one module intentionally — splitting tightly-related
 # validation logic purely to satisfy a line count would hurt readability.
-max-module-lines=1350
+max-module-lines=1400
 
 # Allow the body of a class to be on the same line as the declaration if body
 # contains single statement.

CHANGELOG.md

@@ -4,6 +4,12 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/), and this project adheres to [Semantic Versioning](https://semver.org/).
 
+## [Unreleased]
+
+### Fixed
+
+- **`validate.py` now flags `WorkflowCustomVariable.<name>` references to variables that nothing declares** — a release-only failure. A reference to a custom variable that no `CreateVariable` (or `UpdateVariable` setter) declares imports and validates cleanly, then fails at release with `property "..." contains unknown variable "WorkflowCustomVariable.<name>"`. The validator now collects declared variable names and reports an undeclared reference before you deploy.
+
 ## [1.1.0] - 2026-08-19
 
 ### Added

skills/authoring/references/yaml-schema.md

@@ -116,6 +116,13 @@ UpdateVariable:
     version_constraint: ~1
 ```
 
+**Every `WorkflowCustomVariable.<name>` you reference must be declared first** — by a
+`CreateVariable` action's `variable_schema.properties` (its keys are the names) or set by an
+`UpdateVariable` block. An undeclared name imports and validates fine, then fails at *release* with
+`property "..." contains unknown variable "WorkflowCustomVariable.<name>"`. To feed a hydrated
+indicator into an enrichment call, reference the producing action's output directly
+(`${data['HydrateDetection.results'][0].URL}`) rather than inventing a custom variable you never create.
+
 **Well-known fixed IDs**:
 - CreateVariable: `702d15788dbbffdf0b68d8e2f3599aa4`
 - UpdateVariable: `6c6eab39063fa3b72d98c82af60deb8a`

skills/authoring/scripts/validate.py

@@ -1031,6 +1031,77 @@ def _validate_pinned_data_paths(data, file_path, issues):
                 break
 
 
+def _collect_declared_variables(data):
+    """Collect every WorkflowCustomVariable name the workflow declares.
+
+    A custom variable becomes real in one of two ways: a ``CreateVariable``
+    action declares it under ``properties.variable_schema.properties`` (its keys
+    are the names), or any action sets it through a ``properties.WorkflowCustomVariable``
+    block (its keys are the names). Recurses into loops so a variable created
+    inside a sub-model still counts.
+    """
+    declared = set()
+
+    def _scan(section):
+        if not isinstance(section, dict):
+            return
+        for action in section.values():
+            if not isinstance(action, dict):
+                continue
+            props = action.get("properties", {})
+            if isinstance(props, dict):
+                schema = props.get("variable_schema", {})
+                if isinstance(schema, dict):
+                    schema_props = schema.get("properties", {})
+                    if isinstance(schema_props, dict):
+                        declared.update(schema_props.keys())
+                setter = props.get("WorkflowCustomVariable", {})
+                if isinstance(setter, dict):
+                    declared.update(setter.keys())
+
+    _scan(data.get("actions", {}))
+    loops = data.get("loops", {})
+    if isinstance(loops, dict):
+        for loop_def in loops.values():
+            if isinstance(loop_def, dict):
+                declared.update(_collect_declared_variables(loop_def))
+    return declared
+
+
+def _validate_custom_variable_refs(data, file_path, issues):
+    """Flag ``WorkflowCustomVariable.<name>`` references to undeclared variables.
+
+    A reference to a custom variable that no ``CreateVariable``/``UpdateVariable``
+    declares imports and api_validates fine, then fails at release with
+    ``property "..." contains unknown variable "WorkflowCustomVariable.<name>"``.
+    Declared names come from the parsed workflow; references are found by scanning
+    the raw file, which catches every form uniformly: ``${data['WorkflowCustomVariable.x']}``,
+    ``${{WorkflowCustomVariable.x}}``, a bare ``WorkflowCustomVariable.x`` in a
+    condition expression or loop ``for.input``, and loop-item ``WorkflowCustomVariable.x.#``
+    (the name is the first segment). The pattern only matches dotted references, so
+    a ``WorkflowCustomVariable:`` setter block or a ``variable_schema`` declaration
+    is never mistaken for a reference.
+    """
+    try:
+        with open(file_path, encoding="utf-8") as handle:
+            content = handle.read()
+    except OSError:
+        return
+    referenced = {m.group(1) for m in re.finditer(r"WorkflowCustomVariable\.(\w+)", content)}
+    if not referenced:
+        return
+    declared = _collect_declared_variables(data)
+    for name in sorted(referenced - declared):
+        issues.append(
+            f"ERROR: reference to undefined WorkflowCustomVariable '{name}' — "
+            f"declare it in a CreateVariable action's variable_schema (or set it "
+            f"via UpdateVariable) before referencing it, or reference a prior "
+            f"action's output directly (e.g. ${{data['<Action>.results'][0].<field>}}). "
+            f"Release rejects an undeclared variable as an unknown variable. "
+            f"Declared: {sorted(declared)}."
+        )
+
+
 def _validate_top_level_shape(data, issues):
     """Flag off-schema top-level keys and a missing ``actions:`` section.
 
@@ -1193,6 +1264,7 @@ def structural_check(file_path):
     _validate_http_output_schema(data, file_path, issues)
     _validate_ngsiem_trigger_fields(trigger, file_path, issues)
     _validate_pinned_data_paths(data, file_path, issues)
+    _validate_custom_variable_refs(data, file_path, issues)
 
     return issues
 

skills/workflows/references/yaml-schema.md

@@ -116,6 +116,13 @@ UpdateVariable:
     version_constraint: ~1
 ```
 
+**Every `WorkflowCustomVariable.<name>` you reference must be declared first** — by a
+`CreateVariable` action's `variable_schema.properties` (its keys are the names) or set by an
+`UpdateVariable` block. An undeclared name imports and validates fine, then fails at *release* with
+`property "..." contains unknown variable "WorkflowCustomVariable.<name>"`. To feed a hydrated
+indicator into an enrichment call, reference the producing action's output directly
+(`${data['HydrateDetection.results'][0].URL}`) rather than inventing a custom variable you never create.
+
 **Well-known fixed IDs**:
 - CreateVariable: `702d15788dbbffdf0b68d8e2f3599aa4`
 - UpdateVariable: `6c6eab39063fa3b72d98c82af60deb8a`

tests/test_validate.py

@@ -1125,6 +1125,9 @@ def test_loop_input_from_custom_variable_is_valid(self, tmp_path):
       DoStuff:
         id: aabbccdd11223344aabbccdd11223344
         name: Do stuff
+        properties:
+          WorkflowCustomVariable:
+            my_items: []
 """
         f.write_text(content)
         issues = validate.structural_check(str(f))
@@ -1412,6 +1415,9 @@ def test_loop_internal_actions_are_not_disjoint(self, tmp_path):
   after:
     id: bbccddee22334455bbccddee22334455
     name: After loop
+    properties:
+      WorkflowCustomVariable:
+        items: []
 """
         f = tmp_path / "loop_reach.yaml"
         f.write_text(content)
@@ -2086,8 +2092,21 @@ def test_request_human_input_variable_recipient_passes(self, tmp_path):
 trigger:
   type: On demand
   next:
-    - AskApproval
+    - InitApprover
 actions:
+  InitApprover:
+    id: 702d15788dbbffdf0b68d8e2f3599aa4
+    class: CreateVariable
+    name: Create variable
+    version_constraint: ~1
+    next:
+      - AskApproval
+    properties:
+      variable_schema:
+        properties:
+          approver_email:
+            type: string
+        type: object
   AskApproval:
     id: {self._REQUEST_HUMAN_INPUT_EMAIL_ID}
     version_constraint: ~1
@@ -3271,3 +3290,125 @@ def test_nested_schema_type_not_mistaken_for_trigger_type(self, tmp_path):
         )
         issues = validate.preflight_check(str(f))
         assert not any("Invalid trigger type" in i for i in issues)
+
+
+class TestCustomVariableRefs:
+    """WorkflowCustomVariable.<name> references must resolve to a declared variable.
+
+    An undeclared reference imports and api_validates fine, then fails at release
+    with `unknown variable "WorkflowCustomVariable.<name>"`. These guard the
+    structural-tier check that catches it before deploy.
+    """
+
+    # A CreateVariable declaring `url_enrichment`, then an HTTP action that
+    # references it. `{ref}` is swapped per-test to the declared or an undeclared name.
+    _BASE = """\
+# Created by the CrowdStrike Falcon Fusion authoring skill
+name: Enrichment
+trigger:
+  type: On demand
+  name: On demand
+  next:
+    - InitVars
+actions:
+  InitVars:
+    id: 702d15788dbbffdf0b68d8e2f3599aa4
+    class: CreateVariable
+    name: Create variable
+    version_constraint: ~1
+    next:
+      - Enrich
+    properties:
+      variable_schema:
+        properties:
+          url_enrichment:
+            type: string
+        type: object
+  Enrich:
+    id: 1ba474f407d9228fc8fa02cdce8ae8ef
+    class: Inline.HTTPRequest
+    name: Cloud HTTP Request
+    version_constraint: ~1
+    properties:
+      http_transaction:
+        request_http_method: GET
+        request_url: "https://example.com/${data['WorkflowCustomVariable.{ref}']}"
+output_fields: []
+"""
+
+    def test_undefined_custom_variable_ref_flagged(self, tmp_path):
+        # Mirrors the real bug: reference url_indicator, which is never declared
+        # (InitVars declares url_enrichment).
+        f = tmp_path / "undef.yaml"
+        f.write_text(self._BASE.replace("{ref}", "url_indicator"))
+        issues = validate.structural_check(str(f))
+        assert any(
+            "url_indicator" in i and i.startswith("ERROR") for i in issues
+        ), issues
+
+    def test_declared_via_create_variable_passes(self, tmp_path):
+        # Referencing the declared name produces no undefined-variable error.
+        f = tmp_path / "declared.yaml"
+        f.write_text(self._BASE.replace("{ref}", "url_enrichment"))
+        issues = validate.structural_check(str(f))
+        assert not any("undefined WorkflowCustomVariable" in i for i in issues), issues
+
+    def test_declared_via_update_variable_setter_passes(self, tmp_path):
+        # A variable declared only by an UpdateVariable setter block (no
+        # CreateVariable) still counts as declared.
+        content = """\
+# Created by the CrowdStrike Falcon Fusion authoring skill
+name: Setter
+trigger:
+  type: On demand
+  name: On demand
+  next:
+    - SetVar
+actions:
+  SetVar:
+    id: 6c6eab39063fa3b72d98c82af60deb8a
+    class: UpdateVariable
+    name: Update variable
+    version_constraint: ~1
+    next:
+      - Email
+    properties:
+      WorkflowCustomVariable:
+        notify_email: soc@example.org
+  Email:
+    id: 07413ef9ba7c47bf5a242799f59902cc
+    name: Send email
+    version_constraint: ~1
+    properties:
+      to:
+        - ${data['WorkflowCustomVariable.notify_email']}
+      subject: Hi
+      msg: Body
+      msg_type: html
+output_fields: []
+"""
+        f = tmp_path / "setter.yaml"
+        f.write_text(content)
+        issues = validate.structural_check(str(f))
+        assert not any("undefined WorkflowCustomVariable" in i for i in issues), issues
+
+    def test_undefined_ref_listed_once(self, tmp_path):
+        # The same undeclared name referenced twice is reported once.
+        content = self._BASE.replace("{ref}", "url_indicator").replace(
+            "output_fields: []",
+            "  Enrich2:\n"
+            "    id: 1ba474f407d9228fc8fa02cdce8ae8ef\n"
+            "    class: Inline.HTTPRequest\n"
+            "    name: Cloud HTTP Request 2\n"
+            "    version_constraint: ~1\n"
+            "    properties:\n"
+            "      http_transaction:\n"
+            "        request_http_method: GET\n"
+            "        request_url: \"https://example.com/${data['WorkflowCustomVariable.url_indicator']}\"\n"
+            "output_fields: []",
+        )
+        f = tmp_path / "twice.yaml"
+        f.write_text(content)
+        issues = validate.structural_check(str(f))
+        matches = [i for i in issues if "url_indicator" in i]
+        assert len(matches) == 1, matches