[Schema Consistency] Schema Consistency Report - 2025-11-22: Security Fields & Type Coercion

[github-actions[bot]]

🔍 Schema Consistency Check - 2025-11-22

This automated analysis examines consistency between the JSON schema, parser implementation, compiler code, documentation, and real workflows. This run focused on security-sensitive fields and type coercion patterns.

Summary

Analysis completed using strategy-006 (Security-Sensitive Field & Type Coercion Audit). This strategy audits security-sensitive fields for proper validation and warnings, and detects type coercion issues where code accepts types not in schema.

Full Report Details

Analysis Overview

• Inconsistencies Found: 4 critical/moderate issues
• Categories Analyzed: Schema, Parser, Compiler, Documentation, Workflows
• Strategy Used: strategy-006 (Security-Sensitive Field & Type Coercion Audit)
• New Strategy: No (proven strategy from 2025-10-25)
• Effectiveness: Very High

---

Critical Issues

1. Float-to-Int Silent Truncation Not Documented in Schema

Severity: MODERATE
Location: pkg/workflow/map_helpers.go:parseIntValue(), pkg/workflow/metrics.go:ConvertToInt()

Problem: Runtime accepts float values for integer fields and silently truncates them with only a log warning. Schema doesn't document this behavior.

Example:

# User writes this:
engine:
  max-turns: 10.5

# Runtime silently converts to:
max-turns: 10

Impact:

• Users may unknowingly lose precision
• External schema validators cannot replicate runtime behavior
• Gap between schema validation and runtime acceptance

Evidence:

case float64:
    intVal := int(v)
    if v != float64(intVal) {
        mapHelpersLog.Printf("Float value %.2f truncated to integer %d", v, intVal)
    }
    return intVal, true

Recommendation: Add $comment to integer fields in schema documenting float truncation behavior:

{
  "type": "integer",
  "$comment": "Runtime accepts float values and truncates to integer with warning"
}

---

2. String-to-Integer Type Coercion Not Documented

Severity: MODERATE
Location: pkg/workflow/engine.go:79-86 (max-turns field)

Problem: Runtime accepts string representations of integers (e.g., "300"), but schema only documents type as integer.

Example:

# Both formats work at runtime:
engine:
  max-turns: 300      # integer (schema-valid)
  max-turns: "300"    # string (schema-invalid, runtime-valid)

Impact:

• Schema validation rejects valid runtime formats
• Users confused when their working YAML fails schema validation
• External validators cannot match runtime behavior

Evidence:

if maxTurns, hasMaxTurns := engineObj["max-turns"]; hasMaxTurns {
    if maxTurnsInt, ok := maxTurns.(int); ok {
        config.MaxTurns = fmt.Sprintf("%d", maxTurnsInt)
    } else if maxTurnsStr, ok := maxTurns.(string); ok {
        config.MaxTurns = maxTurnsStr  // ← String accepted!
    }
}

Affected Fields:

• engine.max-turns
• Potentially other integer fields processed by parseIntValue()

Recommendation: Document polymorphic type acceptance using oneOf or $comment:

{
  "oneOf": [
    {"type": "integer"},
    {"type": "string", "pattern": "^[0-9]+$"}
  ],
  "description": "Maximum turns (integer or string representation)"
}

---

3. Type Coercion in error_patterns Fields

Severity: LOW
Location: pkg/workflow/engine.go:162-176

Problem: The level_group and message_group fields accept int, float64, and uint64 types, but schema only documents them as integer.

Evidence:

if levelGroup, ok := patternMap["level_group"].(int); ok {
    pattern.LevelGroup = levelGroup
} else if levelGroupFloat, ok := patternMap["level_group"].(float64); ok {
    pattern.LevelGroup = int(levelGroupFloat)
} else if levelGroupUint64, ok := patternMap["level_group"].(uint64); ok {
    pattern.LevelGroup = int(levelGroupUint64)
}

Impact: Runtime is more permissive than schema suggests

Recommendation: Document type flexibility in schema

---

4. secret-masking Uses Potentially Dead githubActionsStep Reference

Severity: LOW
Location: pkg/parser/schemas/main_workflow_schema.json:secret-masking.steps

Problem: Previous analysis (strategy-010) identified githubActionsStep as potentially dead code, but secret-masking.steps still references it.

Schema:

"secret-masking": {
  "properties": {
    "steps": {
      "items": {
        "$ref": "#/properties/githubActionsStep"
      }
    }
  }
}

Impact:

• If githubActionsStep is truly dead code, this reference is problematic
• Functionality still works, so definition must be valid
• Possible confusion about step format

Recommendation: Verify githubActionsStep definition status and clarify intended use in secret-masking context

---

Positive Findings

1. Exemplary Security Documentation for github-token

Location: docs/src/content/docs/reference/frontmatter.md:74-93

The github-token field documentation is exemplary for security guidance:

✅ Explicit caution callout
✅ Lists valid formats (secrets expressions only)
✅ Lists invalid formats (plaintext, env vars)
✅ Clear explanation of security rationale
✅ Token precedence hierarchy documented

Quote from docs:

:::caution[Secret Expression Required]
The `github-token` field **must** use a GitHub Actions secret expression
(e.g., `${{ secrets.CUSTOM_PAT }}`). Plaintext tokens are rejected during
compilation to prevent accidental secret leakage.

This is a model for how all security-sensitive fields should be documented.

---

2. Comprehensive Permissions Schema

Location: pkg/parser/schemas/main_workflow_schema.json:permissions

The permissions field has excellent schema quality:

✅ Well-structured oneOf pattern (shorthand vs detailed object)
✅ Enum validation for all permission scopes
✅ Clear descriptions for every permission level
✅ Examples showing both simple and complex usage
✅ Security principle documented ("least privilege")

Example schema:

{
  "description": "GitHub token permissions for the workflow. Use the principle of least privilege - only grant the minimum permissions needed.",
  "oneOf": [
    {
      "type": "string",
      "enum": ["read-all", "write-all", "read", "write"]
    },
    {
      "type": "object",
      "properties": {
        "contents": {
          "enum": ["read", "write", "none"],
          "description": "Permission for repository contents"
        }
      }
    }
  ]
}

---

3. Robust Domain Allowlist Implementation

Location: pkg/workflow/domains.go

The network domain allowlist validation is well-implemented:

✅ Ecosystem identifiers for common tool stacks (node, python, ruby, etc.)
✅ Wildcard domain matching support (*.example.com)
✅ Proper default allowlist for backwards compatibility
✅ Empty allowlist means deny-all (secure default)
✅ Domain deduplication in Copilot domain merging

Secure default code:

// Handle empty allowed list (deny-all case)
if len(network.Allowed) == 0 {
    domainsLog.Print("Empty allowed list, denying all network access")
    return []string{} // Secure: deny all
}

---

4. Permissions Parser Validation

Location: pkg/workflow/permissions.go:104-143

The permissions parser includes proper validation:

✅ Validates shorthand permissions syntax
✅ Rejects invalid all: write combination
✅ Rejects invalid all: read with : none combinations
✅ Graceful handling (returns nil for invalid permissions)

Validation code:

if strValue == "write" {
    permissionsLog.Print("Invalid 'all: write' not allowed, ignoring permissions")
    return // Reject invalid config
}

---

5. Real Workflow Usage Validates Design

Examined 78 production workflows in .github/workflows/*.md:

✅ All use proper permissions syntax
✅ Network allowlists properly configured with ecosystem identifiers
✅ No plaintext tokens found
✅ All security-sensitive fields used correctly

Example from workflows:

permissions:
  contents: read
  issues: write

network:
  allowed:
    - defaults
    - node
  firewall: true

---

Key Insights

Type System Flexibility vs Schema Strictness

The analysis reveals an intentional design choice: the runtime is more permissive than the schema suggests. This improves user experience (accepts more formats) but creates a gap for external validators.

Tradeoff:

• ✅ Pro: Users can write max-turns: "300" (YAML numeric string) and it works
• ✅ Pro: Float values truncate to int instead of hard failing
• ❌ Con: External schema validators reject valid runtime formats
• ❌ Con: Users may not understand type coercion behavior

Recommendation: Document this intentional permissiveness in schema metadata using $comment fields.

---

Security Documentation Excellence

The github-token field demonstrates best practices for security-sensitive configuration:

1. Schema description mentions security principle
2. Documentation has dedicated caution callout
3. Examples show both valid and invalid formats
4. Compiler validation rejects plaintext tokens
5. Token precedence clearly documented

This model should be applied to other security fields like network and permissions.

---

Defense in Depth

The codebase implements multiple layers of validation:

1. Schema: Type and structure validation
2. Parser: YAML parsing and initial validation
3. Compiler: Business logic validation (e.g., reject invalid permission combos)
4. Runtime: Type coercion and graceful handling

Each layer adds value, but the gaps between layers create the inconsistencies found in this analysis.

---

Recommendations

High Priority

1. Document Type Coercion Behavior

   • Add $comment to integer fields explaining float truncation
   • Add $comment documenting string-to-int conversion
   • Consider oneOf for polymorphic fields (int | string)

2. Verify githubActionsStep Definition

   • Clarify if this is actually dead code or still used
   • Update secret-masking reference if needed
   • Consider inlining step definition if only used once

Medium Priority

3. Standardize Type Flexibility

   • Decide if runtime should be stricter OR schema should be more permissive
   • Document the design decision
   • Apply consistently across all numeric fields

4. Expand Security Warnings

   • Apply github-token documentation model to network field
   • Add security caution callouts for permissions field
   • Document ecosystem identifiers and their security implications

Low Priority

5. Consider Stricter Validation Mode
   • Add optional --strict-types flag to compiler
   • Reject float-to-int coercion in strict mode
   • Useful for catching config errors early

---

Schema Field Coverage

Analyzed 4 security-sensitive fields:

Field	Schema	Parser	Compiler	Docs	Status
permissions	✅ Excellent	✅ Validated	✅ Complex logic	✅ Complete	✅ Consistent
github-token	✅ Good	✅ Extracted	✅ Validated	✅ Exemplary	✅ Consistent
network	✅ Good	✅ Extracted	✅ Validated	✅ Good	✅ Consistent
secret-masking	⚠️ Dead ref?	✅ Extracted	✅ Compiled	✅ Documented	⚠️ Minor issue

---

Type Coercion Matrix

Runtime type acceptance vs schema definitions:

Field	Schema Type	Runtime Accepts	Documented?
max-turns	integer	int, uint64, string	❌ No
level_group	integer	int, float64, uint64	❌ No
message_group	integer	int, float64, uint64	❌ No
Any integer	integer	float64 (truncated)	❌ No

Impact: 4 undocumented type coercion patterns

---

Strategy Performance

• Strategy: strategy-006 (Security-Sensitive Field & Type Coercion Audit)
• Last Used: 2025-10-25 (almost 1 month ago)
• This Run: 2025-11-22
• Findings: 9 total (4 issues, 5 positive findings)
• Effectiveness: Very High
• Recommendation: Continue using every 3-4 weeks

Why This Strategy Works:

• Focuses on high-impact security fields
• Reveals runtime vs schema mismatches
• Complements field-level validation strategies
• Finds issues missed by static schema analysis

---

Next Steps

Immediate Actions

• Add $comment fields documenting type coercion behavior
• Verify githubActionsStep reference validity
• Consider oneOf for polymorphic integer fields

Follow-up Analysis

• Run strategy-017 (Runtime Type Behavior) to deep-dive type coercion
• Run strategy-003 (Required Field Enforcement) to check validation completeness
• Consider new strategy for security field documentation quality

Long-term Improvements

• Establish type coercion policy (permissive runtime vs strict schema)
• Create security documentation template based on github-token model
• Add compiler flag for strict type validation mode

---

Conclusion

Overall Assessment: The security-sensitive fields show excellent implementation quality with only minor documentation gaps. The main finding is that runtime type coercion is more permissive than schema suggests, which is intentional for user experience but should be documented.

No Critical Security Issues Found. All security validations are working correctly:

• ✅ Permissions validation rejects invalid combinations
• ✅ Token validation prevents plaintext tokens
• ✅ Network allowlist implements deny-by-default
• ✅ Secret-masking properly configured

The issues found are documentation and schema metadata gaps, not security vulnerabilities.

---

Strategy Used: strategy-006 (Security-Sensitive Field & Type Coercion Audit)
Date: 2025-11-22
Next Recommended Strategy: strategy-017 (Runtime Type Behavior vs Schema Type Definitions)

AI generated by Schema Consistency Checker

[github-actions[bot]]

This discussion was automatically closed because it was created by an agentic workflow more than 1 week ago.