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 files are generated by running terraform plan -out=tfplan.binary followed by terraform show -json tfplan.binary. This produces a machine-readable JSON representation of your planned infrastructure changes, including resources and their attributes. 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"

Ensure storage_encrypted is true and kms_key_id is not empty

Ensure os_disk.encryption_settings.enabled is true

Terraform Files (HCL Format)¶

Terraform files written in HCL (HashiCorp Configuration Language) describe resources and their configuration in a human-readable format. Prompts should reference resource blocks and their attributes as defined in HCL.

API Instruction Object:

instruction:
  rule: "Ensure all aws_s3_bucket resources have versioning enabled"
  format: "hcl"
  category: "terraform"
  type: "aws_s3_bucket"

Prompt Examples:

Ensure all aws_s3_bucket resources have versioning enabled

Check that aws_security_group ingress rules do not allow 0.0.0.0/0 on port 22

Require all aws_rds_instance resources to have storage_encrypted set to true

Kubernetes YAML Manifests¶

Kubernetes resources follow the standard API structure with apiVersion, kind, metadata, and spec. You can use natural language to describe the desired state or behavior, and Aegis will infer the correct attributes.

API Instruction Object:

instruction:
  rule: "Ensure containers do not run as root user"
  format: "yaml"
  category: "kubernetes"
  type: "Deployment"

Prompt Examples:

Ensure containers do not run as root user

Prevent privilege escalation in containers

Do not allow NodePort services in the production namespace

Ingress must use the nginx controller

CloudFormation Templates¶

CloudFormation templates use a Resources section with resource types and their Properties. You can use natural language to describe the desired state, but referencing exact property names is helpful for precision.

API Instruction Object:

instruction:
  rule: "Ensure S3 buckets have versioning enabled"
  format: "yaml"
  category: "cloudformation"
  type: "AWS::S3::Bucket"

Prompt Examples:

Ensure S3 buckets have versioning enabled

Block public access to all S3 buckets

Do not allow security groups to have egress rules to 0.0.0.0/0

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.