Ruleset Prompting Guide¶

Effective prompting is crucial for generating accurate and reliable rulesets in Aegis. This guide provides detailed best practices and examples for crafting prompts that will result in high-quality rules tailored to your specific input types and resources.

Core Principles¶

1. Understand Your Input Type¶

While you don't need to specify the input type (e.g., "Terraform Plan JSON") or the resource type (e.g., "AWS S3 Bucket") in the prompt itself—as this is handled by the UI or API—your prompt must be tailored to the specific structure of that input.

Different input formats have unique data structures, and your prompt must use keywords and field names that are specific to that format for Aegis to generate an accurate rule.

2. Focus on Attribute-Specific Keywords¶

This is the most critical principle. Use the exact field names, property keys, and attribute identifiers that exist in your input format. This ensures Aegis can accurately locate and evaluate the relevant data.

Example: For a Terraform plan of an AWS SNS topic, use kms_master_key_id in your prompt because that is the exact attribute name in the plan.

Prompting Patterns by Input Type¶

Terraform Plan JSON¶

Terraform plan JSON has a specific structure with planned_values, resource_changes, and configuration sections. Use field names exactly as they appear in the Terraform provider documentation. The input type and resource type are specified separately in the UI/API, so focus your prompt on the validation logic.

API Instruction Object:

instruction:
  rule: "Validate that kms_master_key_id is not empty"
  format: "json"
  category: "terraform-plan"
  type: "aws_sns_topic"

Prompt Examples:

Validate that kms_master_key_id is not empty

Validate that versioning.enabled is true and versioning.mfa_delete is true

Validate that enable_https_traffic_only is true and min_tls_version is "TLS1_2"

Validate that boot_disk.initialize_params.type is not "pd-standard"

Terraform State JSON¶

Terraform state uses resources array with instances containing the actual values. Reference attributes as they exist in the state file.

API Instruction Object:

instruction:
  rule: "Ensure storage_encrypted is true and kms_key_id is not empty"
  format: "json"
  category: "terraform-plan"
  type: "aws_rds_instance"

Prompt Examples:

Ensure storage_encrypted is true and kms_key_id is not empty

Ensure os_disk.encryption_settings.enabled is true

Kubernetes YAML Manifests¶

Kubernetes resources follow the standard API structure with apiVersion, kind, metadata, and spec. Use exact field paths as defined in the Kubernetes API.

API Instruction Object:

instruction:
  rule: "Validate that spec.template.spec.securityContext.runAsNonRoot is true"
  format: "yaml"
  category: "kubernetes"
  type: "Deployment"

Prompt Examples:

Validate that spec.template.spec.securityContext.runAsNonRoot is true

Validate that spec.containers[].securityContext.allowPrivilegeEscalation is false

Validate that spec.type is not "NodePort" when metadata.namespace is "production"

Validate that metadata.annotations["kubernetes.io/ingress.class"] equals "nginx"

CloudFormation Templates¶

CloudFormation uses Resources section with resource types and Properties. Reference AWS resource properties exactly as documented.

API Instruction Object:

instruction:
  rule: "Validate that Properties.VersioningConfiguration.Status equals 'Enabled'"
  format: "yaml"
  category: "cloudformation"
  type: "AWS::S3::Bucket"

Prompt Examples:

Validate that Properties.VersioningConfiguration.Status equals "Enabled"

Validate that Properties.SecurityGroupEgress does not contain CidrIp "0.0.0.0/0"

ARM Templates¶

ARM templates use resources array with type and properties. Use exact property names from Azure Resource Manager documentation.

API Instruction Object:

instruction:
  rule: "Validate that properties.supportsHttpsTrafficOnly is true"
  format: "json"
  category: "azure-resource"
  type: "Microsoft.Storage/storageAccounts"

Prompt Examples:

Validate that properties.supportsHttpsTrafficOnly is true

Validate that properties.osProfile.linuxConfiguration.disablePasswordAuthentication is true

Advanced Prompting Techniques¶

Multi-Condition Rules¶

While you can combine multiple conditions in a single prompt, it is usually better to create individual rules for each condition. This approach improves granularity, makes maintenance easier, and provides clearer feedback when a rule fails.

Not recommended:

Validate that load_balancer_type is "application" and security_groups is not empty and subnets contains at least 2 elements

Recommended:

Validate that load_balancer_type is "application"
Validate that security_groups is not empty
Validate that subnets contains at least 2 elements

Conditional Logic¶

Use conditional statements for context-aware rules:

Validate that if containers name contains "latest" then metadata namespace must not be "production"

Array and List Validation¶

Be specific about array operations and element requirements:

Validate that ingress rules do not contain any rule where from_port is 22 and cidr_blocks contains "0.0.0.0/0"

Regular Expression Patterns¶

When you need to enforce a specific naming convention or pattern, you do not need to provide a complex regular expression. You can achieve the same result by providing examples of strings that should and should not match the desired pattern in your prompt. Aegis will infer the pattern from your examples.

Prompt Example:

Ensure container images follow our naming convention.
Good examples: "my-registry.com/my-app:1.2.3", "internal-repo/backend-service:latest-stable"
Bad examples: "my-app:latest", "random-image"

This approach is often easier and more readable than writing and debugging regular expressions. However, if you prefer, you can still provide a specific regex pattern.

Resource-Specific Keywords Reference¶

AWS Resources (Terraform)¶

Resource Type	Common Attributes
`aws_s3_bucket`	`versioning`, `server_side_encryption_configuration`, `public_access_block`
`aws_rds_instance`	`storage_encrypted`, `kms_key_id`, `backup_retention_period`
`aws_security_group`	`ingress`, `egress`, `from_port`, `to_port`, `cidr_blocks`
`aws_sns_topic`	`kms_master_key_id`, `delivery_policy`
`aws_sqs_queue`	`kms_master_key_id`, `message_retention_seconds`
`aws_lambda_function`	`environment`, `kms_key_arn`, `reserved_concurrent_executions`

Kubernetes Resources¶

Resource Kind	Common Spec Paths
`Deployment`	`spec.template.spec.securityContext`, `spec.template.spec.containers[].resources`
`Pod`	`spec.securityContext`, `spec.containers[].securityContext`, `spec.containers[].resources`
`Service`	`spec.type`, `spec.ports`, `spec.selector`
`Ingress`	`spec.rules`, `spec.tls`, `metadata.annotations`
`ConfigMap`	`data`, `metadata.labels`
`Secret`	`type`, `data`, `metadata.labels`

Azure Resources (ARM/Terraform)¶

Resource Type	Common Properties
`Microsoft.Storage/storageAccounts`	`supportsHttpsTrafficOnly`, `minimumTlsVersion`, `allowBlobPublicAccess`
`Microsoft.Compute/virtualMachines`	`osProfile`, `storageProfile.osDisk.managedDisk.storageAccountType`
`Microsoft.Network/networkSecurityGroups`	`securityRules`, `defaultSecurityRules`
`Microsoft.KeyVault/vaults`	`enabledForDiskEncryption`, `enablePurgeProtection`

Testing Your Prompts¶

Start Simple: Begin with basic validation rules and gradually add complexity
Use Sample Data: Provide representative sample data to validate your prompt accuracy
Test Edge Cases: Consider boundary conditions and error scenarios
Iterate: Refine your prompts based on the generated rules and test results

Best Practices Summary¶

Be Specific: Use exact attribute names and resource types
Include Context: Always specify the input format and target platform
Use Examples: Reference the sample patterns provided above
Test Thoroughly: Validate generated rules against known good and bad configurations
Document Intent: Include the business reason or compliance requirement in complex rules
Start Granular: Create focused rules rather than attempting to validate everything in one prompt

By following these guidelines, you'll create more accurate, maintainable, and effective rulesets that properly validate your infrastructure and application configurations.