[EDI] Using custom queries with the CodeQL CLI (#59665)

Co-authored-by: Sam Browning <106113886+sabrowning1@users.noreply.github.com>

Author: mchammer01

content/code-security/concepts/code-scanning/codeql/codeql-query-packs.md

@@ -16,7 +16,22 @@ contentType: concepts
 
 ## About {% data variables.product.prodname_codeql %} packs
 
-{% data variables.product.prodname_codeql %} packs are used to create, share, depend on, and run {% data variables.product.prodname_codeql %} queries and libraries. {% data variables.product.prodname_codeql %} packs contain queries, library files, query suites, and metadata. You can customize your {% data variables.product.prodname_codeql %} analysis by downloading packs created by others and running them on your codebase.
+{% data variables.product.prodname_codeql %} packs are used to create, share, depend on, and run {% data variables.product.prodname_codeql %} queries and libraries. You can customize your {% data variables.product.prodname_codeql %} analysis by downloading packs created by others and running them on your codebase.
+
+Each {% data variables.product.prodname_codeql %} pack requires a `qlpack.yml` file in its root directory that specifies:
+
+* How to compile the queries
+* Dependencies on other {% data variables.product.prodname_codeql %} packs and libraries
+* Query suite definitions
+
+For more information about `qlpack.yml` properties, see [AUTOTITLE](/code-security/codeql-cli/getting-started-with-the-codeql-cli/customizing-analysis-with-codeql-packs#codeqlpack-yml-properties).
+
+Additionally, a {% data variables.product.prodname_codeql %} pack can contain:
+
+* Custom queries (`.ql` files)
+* Library files
+* Query suites
+* Metadata
 
 The {% data variables.product.prodname_codeql_cli %} bundle includes queries that are maintained by {% data variables.product.company_short %} experts, security researchers, and community contributors. If you want to run queries developed by other organizations, {% data variables.product.prodname_codeql %} query packs provide an efficient and reliable way to download and run queries, while model packs ({% data variables.release-phases.public_preview %}) can be used to expand {% data variables.product.prodname_code_scanning %} analysis to recognize libraries and frameworks that are not supported by default.
 
@@ -47,4 +62,13 @@ For more information about compatibility between published query packs and diffe
 
 You can also use the {% data variables.product.prodname_codeql_cli %} to create your own {% data variables.product.prodname_codeql %} packs, add dependencies to packs, and install or update dependencies.
 
-You can publish {% data variables.product.prodname_codeql %} packs that you have created, using the {% data variables.product.prodname_codeql_cli %}. For more information on publishing and downloading {% data variables.product.prodname_codeql %} packs, see [AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/publishing-and-using-codeql-packs).
+## Publishing and sharing {% data variables.product.prodname_codeql %} packs
+
+You can share custom queries with the broader {% data variables.product.prodname_codeql %} community by:
+
+* Publishing to {% data variables.product.prodname_registry %}: Make your pack publicly available for other users to discover and use.
+* Contributing to the {% data variables.product.prodname_codeql %} repository: Submit queries that would benefit the wider community by opening a pull request to the official repository.
+
+For more information about publishing and downloading {% data variables.product.prodname_codeql %} packs, see [AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/publishing-and-using-codeql-packs).
+
+For information about contributing to {% data variables.product.prodname_codeql %}, see [Contributing to {% data variables.product.prodname_codeql %}](https://github.com/github/codeql/blob/main/CONTRIBUTING.md).

content/code-security/concepts/code-scanning/codeql/custom-codeql-queries.md

@@ -0,0 +1,66 @@
+---
+title: Custom CodeQL queries
+shortTitle: Custom queries
+intro: Custom queries extend {% data variables.product.prodname_codeql %}'s built-in security analysis to detect vulnerabilities and enforce coding standards specific to your codebase.
+product: '{% data reusables.gated-features.codeql %}'
+versions:
+  fpt: '*'
+  ghes: '*'
+  ghec: '*'
+topics:
+  - Code Security
+  - Code scanning
+  - CodeQL
+contentType: concepts
+---
+
+## What are custom {% data variables.product.prodname_codeql %} queries?
+
+Custom queries extend {% data variables.product.prodname_codeql %}'s built-in security analysis to detect vulnerabilities, coding standards, and patterns specific to your codebase.
+
+{% data reusables.codeql-cli.advanced-query-execution %}
+
+## When to use custom queries
+
+Use custom queries to:
+
+* Detect vulnerabilities specific to your application's architecture or frameworks
+* Enforce organization-specific coding standards or best practices
+* Find patterns not covered by standard {% data variables.product.prodname_codeql %} query packs
+* Analyze {% data variables.product.prodname_codeql %} databases with the `database analyze` command using the {% data variables.product.prodname_codeql_cli %} to produce interpreted results
+
+## Query structure
+
+Custom queries are written in query files, which are saved with the `.ql` extension. These files also contain important metadata that provides information about the query's purpose and tells the {% data variables.product.prodname_codeql_cli %} how to process results. Required properties include:
+
+* **Query identifier (`@id`)**: Lowercase letters or digits, delimited by `/` or `-`
+* **Query type (`@kind`)**: One of:
+  * `problem` - Simple alert
+  * `path-problem` - Alert with code location sequence
+  * `diagnostic` - Extractor troubleshooting
+  * `metric` - Summary metric (requires `@tags summary`)
+
+> [!NOTE]
+> Metadata requirements may differ if you want to use your query with other applications. For more information, see [Metadata for {% data variables.product.prodname_codeql %} queries](https://codeql.github.com/docs/writing-codeql-queries/metadata-for-codeql-queries/#metadata-for-codeql-queries).
+
+For more information about query metadata, see [Metadata for {% data variables.product.prodname_codeql %} queries](https://codeql.github.com/docs/writing-codeql-queries/metadata-for-codeql-queries/#metadata-for-codeql-queries) and the [Query metadata style guide](https://github.com/github/codeql/blob/main/docs/query-metadata-style-guide.md).
+
+## Query documentation
+
+Query documentation helps users understand what a query detects and how to address identified issues. You can include documentation for your custom queries in two formats:
+
+* **Markdown files**: Saved alongside the query, can be included in SARIF files and displayed in the {% data variables.product.prodname_code_scanning %} UI
+* **`.qhelp` files**: Consistent with standard {% data variables.product.prodname_codeql %} queries, but must be converted to Markdown for use with {% data variables.product.prodname_code_scanning %}
+
+When SARIF files containing query help are uploaded to {% data variables.product.prodname_dotcom %}, the documentation appears in the {% data variables.product.prodname_code_scanning %} UI for any alerts generated by the query.
+
+For more information, see [Query help files](https://codeql.github.com/docs/writing-codeql-queries/query-help-files/#query-help-files).
+
+## Sharing custom queries
+
+You can share custom queries with the community by publishing your own query packs. See [AUTOTITLE](/code-security/tutorials/customize-code-scanning/publishing-and-using-codeql-packs).
+
+## Further reading
+
+* [AUTOTITLE](/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-the-command-line/using-custom-queries-with-the-codeql-cli)
+* [{% data variables.product.prodname_codeql %} queries](https://codeql.github.com/docs/writing-codeql-queries/codeql-queries/#codeql-queries)

content/code-security/concepts/code-scanning/codeql/index.md

@@ -12,6 +12,7 @@ contentType: concepts
 children:
   - /about-code-scanning-with-codeql
   - /codeql-query-suites
+  - /custom-codeql-queries
   - /about-the-codeql-cli
   - /about-codeql-for-vs-code
   - /about-codeql-workspaces

content/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-the-command-line/index.md

@@ -13,7 +13,7 @@ topics:
 children:
   - /setting-up-the-codeql-cli
   - /advanced-setup-of-the-codeql-cli
-  - /using-custom-queries-with-the-codeql-cli
+  - /writing-and-sharing-custom-queries-for-the-codeql-cli
   - /testing-custom-queries
   - /testing-query-help-files
   - /specifying-command-options-in-a-codeql-configuration-file