IaC Comment Class

iac/ql/lib/codeql/hcl/ast/AstNodes.qll

@@ -100,12 +100,12 @@ class HclAstNode extends THclAstNode {
  * }
  * ```
  */
-class Comment extends HclAstNode, TComment {
+class HCLComment extends HclAstNode, TComment {
  private HCL::Comment comment;
 
- override string getAPrimaryQlClass() { result = "Comment" }
+ override string getAPrimaryQlClass() { result = "HCLComment" }
 
-Comment() { this = TComment(comment) }
+HCLComment() { this = TComment(comment) }
 
  /** Gets the textual contents of the comment. */
  string getContents() { result = comment.getValue() }

iac/ql/lib/codeql/iac/Comments.qll

@@ -0,0 +1,93 @@
+/**
+ * Provides a unified representation of comments across the infrastructure-as-code
+ * (IaC) languages supported by CodeQL, spanning HCL/Terraform comments and comments
+ * in YAML files recognized by a public IaC framework API.
+ */
+
+import iac
+
+/**
+ * Holds if `file` is a YAML file recognized by a public IaC framework API.
+ */
+private predicate isSupportedYamlFile(File file) {
+ exists(CloudFormation::Document document | document.getFile() = file)
+ or
+ exists(ARM::Document document | document.getFile() = file)
+ or
+ exists(AzurePipelines::Document document | document.getFile() = file)
+ or
+ exists(Compose::Document document | document.getFile() = file)
+ or
+ exists(HelmChart::Document document | document.getFile() = file)
+ or
+ exists(OpenApi::Document document | document.getFile() = file)
+ or
+ exists(YamlDocument document |
+ document.getFile() = file and
+ document instanceof YamlMapping and
+ document
+ .(YamlMapping)
+ .lookup("$schema")
+ .(YamlString)
+ .getValue()
+ .regexpMatch(".*schema\\.management\\.azure\\.com.*")
+ )
+}
+
+/**
+ * Gets the delimiter-stripped `text` and `delimiterStyle` of an HCL comment.
+ */
+private predicate getHclCommentText(HCLComment comment, string text, string delimiterStyle) {
+ exists(string raw | raw = comment.getContents() |
+ raw.matches("#%") and
+ text = raw.suffix(1).replaceAll("\r", "") and
+ delimiterStyle = "hash"
+ or
+ raw.matches("//%") and
+ text = raw.suffix(2).replaceAll("\r", "") and
+ delimiterStyle = "slash"
+ or
+ raw.matches("/*%*/") and
+ text = raw.substring(2, raw.length() - 2).replaceAll("\r", "") and
+ delimiterStyle = "slash"
+ )
+}
+
+/**
+ * Gets the delimiter-stripped `text` and `delimiterStyle` of a comment exposed by a
+ * supported public IaC API located at `location`.
+ */
+private predicate getIacCommentText(Location location, string text, string delimiterStyle) {
+ exists(HCLComment comment |
+ location = comment.getLocation() and
+ getHclCommentText(comment, text, delimiterStyle)
+ )
+ or
+ exists(YamlComment comment |
+ location = comment.getLocation() and
+ isSupportedYamlFile(comment.getLocation().getFile()) and
+ text = comment.getText() and
+ delimiterStyle = "hash"
+ )
+}
+
+/**
+ * A comment exposed by a supported public IaC API.
+ *
+ * This spans HCL/Terraform comments and comments in YAML files recognized by a public
+ * IaC framework API (for example CloudFormation, ARM, Azure Pipelines, Compose, Helm
+ * charts and OpenAPI documents).
+ */
+class Comment extends Location {
+ Comment() {
+ exists(string text, string delimiterStyle | getIacCommentText(this, text, delimiterStyle))
+ }
+
+ /** Gets the comment text without its delimiter. */
+ string getText() {
+ exists(string delimiterStyle | getIacCommentText(this, result, delimiterStyle))
+ }
+
+ /** Holds if this comment uses `#` as its delimiter. */
+ predicate hasHashDelimiter() { exists(string text | getIacCommentText(this, text, "hash")) }
+}

iac/ql/lib/iac.qll

@@ -1,5 +1,6 @@
 import codeql.Locations
 import codeql.files.FileSystem
+import codeql.iac.Comments
 import codeql.iac.Dependencies
 // Azure
 import codeql.iac.azure.ARM

iac/ql/test/library-tests/comments/Comments.expected

@@ -0,0 +1,16 @@
+iacComments
+| sample.hcl:1:1:1:16 | sample.hcl@1:1:1:16 |
+| sample.hcl:2:1:2:18 | sample.hcl@2:1:2:18 |
+| sample.hcl:3:1:3:21 | sample.hcl@3:1:3:21 |
+| sample.hcl:6:24:6:47 | sample.hcl@6:24:6:47 |
+| template.yml:3:3:3:28 | template.yml@3:3:3:28 |
+getText
+| sample.hcl:1:1:1:16 | sample.hcl@1:1:1:16 | a hash comment |
+| sample.hcl:2:1:2:18 | sample.hcl@2:1:2:18 | a slash comment |
+| sample.hcl:3:1:3:21 | sample.hcl@3:1:3:21 | a block comment |
+| sample.hcl:6:24:6:47 | sample.hcl@6:24:6:47 | an inline hash comment |
+| template.yml:3:3:3:28 | template.yml@3:3:3:28 | a supported YAML comment |
+hasHashDelimiter
+| sample.hcl:1:1:1:16 | sample.hcl@1:1:1:16 |
+| sample.hcl:6:24:6:47 | sample.hcl@6:24:6:47 |
+| template.yml:3:3:3:28 | template.yml@3:3:3:28 |

iac/ql/test/library-tests/comments/Comments.ql

@@ -0,0 +1,7 @@
+private import iac
+
+query predicate iacComments(Comment c) { any() }
+
+query predicate getText(Comment c, string text) { text = c.getText() }
+
+query predicate hasHashDelimiter(Comment c) { c.hasHashDelimiter() }

iac/ql/test/library-tests/comments/sample.hcl

@@ -0,0 +1,7 @@
+# a hash comment
+// a slash comment
+/* a block comment */
+
+resource "aws_instance" "example" {
+ ami = "ami-12345678" # an inline hash comment
+}

iac/ql/test/library-tests/comments/template.yml

@@ -0,0 +1,5 @@
+AWSTemplateFormatVersion: "2010-09-09"
+Resources:
+ # a supported YAML comment
+ ExampleBucket:
+ Type: AWS::S3::Bucket

iac/ql/test/library-tests/comments/unsupported.yml

@@ -0,0 +1,2 @@
+# an unsupported YAML comment that should be ignored
+foo: bar