control_narrative

Instructions

Implementation Reference

• src/tools/compliance/control-narrative.ts:71-129 (handler)

  Main handler function for the control_narrative tool. Uses runTool wrapper with Zod schema validation, fetches ESLZ grounding context (Azure Enterprise Scale policies/architecture), builds a prompt via controlNarrativeTemplate, calls Anthropic Claude API, and returns the AI-generated eMASS-ready control implementation narrative.

  export async function handleControlNarrative(args: unknown): Promise<string> {
    return runTool('control_narrative', args, Schema, async ({ controlId, systemName, systemDescription, azureServices, cspLevel: rawCspLevel, impactLevel, organizationName }) => {
      const cspLevel = rawCspLevel
        .replace('gcc-high', 'azure-gcc-high')
        .replace('azure-gov', 'azure-government');
      const controlFamily = controlId.split('-')[0];
  
      // Fetch ESLZ grounding context in parallel — graceful degradation on failure
      const [policyDefs, archDoc] = await Promise.all([
        fetchEslzContent('eslzArm/managementGroupTemplates/policyDefinitions/policies.json'),
        fetchEslzContent('README.md'),
      ]);
  
      const eslzAvailable = !!(policyDefs || archDoc);
  
      let groundingContext = '';
      if (eslzAvailable) {
        const relevantPolicies = extractRelevantPolicies(policyDefs, controlFamily, azureServices);
        const archGuidance = extractRelevantArchGuidance(archDoc, controlFamily);
  
        const sections: string[] = [];
        if (relevantPolicies) {
          sections.push(`## Azure Enterprise Scale Policy Definitions (Official Microsoft Source)
  The following are real Azure Policy definitions from the official Azure/Enterprise-Scale repository relevant to ${controlId}:
  
  ${relevantPolicies}`);
        }
        if (archGuidance) {
          sections.push(`## Azure Landing Zone Design Guidance (Official Microsoft Source)
  ${archGuidance}`);
        }
        groundingContext = sections.join('\n\n');
      }
  
      const basePrompt = controlNarrativeTemplate(
        controlId,
        systemName,
        systemDescription,
        azureServices,
        cspLevel,
        impactLevel,
        organizationName
      );
  
      const fullPrompt = groundingContext
        ? `${basePrompt}\n\n## Grounding Context — Official Microsoft Azure/Enterprise-Scale Repository\nUse the following official Microsoft content to ensure your narrative references real Azure Policy definition names and accurate ALZ architecture patterns:\n\n${groundingContext}`
        : basePrompt;
  
      const response = await anthropic.messages.create({
        model: MODEL,
        max_tokens: getTokenBudget('control_narrative'),
        system: NARRATIVE_SYSTEM,
        messages: [{ role: 'user', content: fullPrompt }],
      });
  
      const text = response.content[0].type === 'text' ? response.content[0].text : '';
      return eslzAvailable ? text + ESLZ_ATTRIBUTION : text;
    });
  }

• src/tools/compliance/control-narrative.ts:43-54 (schema)

  Zod schema (Schema) validating: controlId (NIST format regex), systemName, systemDescription, azureServices, cspLevel (enum), impactLevel (enum), and optional organizationName.

  const Schema = z.object({
    controlId: z.string().regex(
      /^[A-Z]{2}-\d{1,2}(\(\d{1,2}\))?$/,
      'Control ID must be NIST format: e.g. AC-2, SC-28, AC-2(1)'
    ),
    systemName: z.string().max(500),
    systemDescription: z.string().max(2000),
    azureServices: z.array(z.string().max(500)).max(50),
    cspLevel: z.enum(['azure-commercial', 'azure-government', 'azure-gcc-high', 'gcc-high', 'azure-gov']),
    impactLevel: z.enum(['low', 'moderate', 'high', 'il4', 'il5']),
    organizationName: z.string().max(500).optional(),
  });

• src/tools/index.ts:60-87 (registration)

  Dispatch in handleToolCall: case 'control_narrative' routes to handleControlNarrative(args).

  export async function handleToolCall(name: string, args: unknown): Promise<string> {
    switch (name) {
      case 'bicep_analyze':         return handleBicepAnalyze(args);
      case 'bicep_remediate':       return handleBicepRemediate(args);
      case 'control_lookup':        return handleControlLookup(args);
      case 'control_narrative':     return handleControlNarrative(args);
      case 'poam_generate':         return handlePoamGenerate(args);
      case 'ato_readiness':         return handleAtoReadiness(args);
      case 'oscal_fragment':        return handleOscalFragment(args);
      case 'landing_zone_design':   return handleLandingZone(args);
      case 'landing_zone_reference': return handleLandingZoneReference(args);
      case 'azure_service_selector': return handleServiceSelect(args);
      case 'gcc_high_guidance':     return handleGccHigh(args);
      case 'private_endpoint_map':  return handlePrivateEndpoint(args);
      case 'bigbang_validate':      return handleBigbangValidate(args);
      case 'bigbang_harden':        return handleBigbangHarden(args);
      case 'ironbank_lookup':       return handleIronbankLookup(args);
      case 'addon_configurator':    return handleAddonConfigurator(args);
      case 'pipeline_audit':        return handlePipelineAudit(args);
      case 'signing_config':        return handleSigningConfig(args);
      case 'devsecops_scorecard':   return handleDevsecopsScorecard(args);
      case 'ssp_section':           return handleSspSection(args);
      case 'contingency_plan':      return handleContingencyPlan(args);
      case 'govcloud_quickstart':   return handleGovcloudQuickstart(args);
      default:
        throw new Error(`Unknown tool: ${name}`);
    }
  }

• src/tools/index.ts:29-58 (registration)

  Tool object registered in allTools array at line 34, imported from './compliance/control-narrative.js'.

  export const allTools = [
    // Compliance
    bicepAnalyzeTool,
    bicepRemediateTool,
    controlLookupTool,
    controlNarrativeTool,
    poamGenerateTool,
    atoReadinessTool,
    oscalFragmentTool,
    // Architecture
    landingZoneTool,
    landingZoneReferenceTool,
    serviceSelectTool,
    gccHighTool,
    privateEndpointTool,
    // Platform One
    bigbangValidateTool,
    bigbangHardenTool,
    ironbankLookupTool,
    addonConfiguratorTool,
    // Pipeline
    pipelineAuditTool,
    signingConfigTool,
    devsecopsScoreCardTool,
    // Documents
    sspSectionTool,
    contingencyPlanTool,
    // Meta
    govcloudQuickstartTool,
  ];

• src/tools/compliance/control-narrative.ts:12-41 (schema)

  Tool definition object with name 'control_narrative', description, and input JSON Schema (properties for controlId, systemName, systemDescription, azureServices, cspLevel, impactLevel, organizationName).

  export const controlNarrativeTool = {
    name: 'control_narrative',
    description:
      'Generate eMASS-ready control implementation narratives for any NIST 800-53 Rev 5 control given your system description. Output is AO-review quality prose.',
    inputSchema: {
      type: 'object' as const,
      properties: {
        controlId: { type: 'string', description: 'e.g. "AC-2", "SC-28"' },
        systemName: { type: 'string', description: 'Name of the system' },
        systemDescription: { type: 'string', description: 'What the system does' },
        azureServices: {
          type: 'array',
          items: { type: 'string' },
          description: 'Azure services in scope',
        },
        cspLevel: {
          type: 'string',
          enum: ['azure-commercial', 'azure-government', 'azure-gcc-high', 'gcc-high', 'azure-gov'],
          description: 'Cloud service provider level',
        },
        impactLevel: {
          type: 'string',
          enum: ['low', 'moderate', 'high', 'il4', 'il5'],
          description: 'System impact level',
        },
        organizationName: { type: 'string', description: 'Organization name (optional)' },
      },
      required: ['controlId', 'systemName', 'systemDescription', 'azureServices', 'cspLevel', 'impactLevel'],
    },
  };