From 58cc8b64b363165b8fca53da36ac4f419d76cc2d Mon Sep 17 00:00:00 2001 From: docs-bot <77750099+docs-bot@users.noreply.github.com> Date: Fri, 4 Oct 2024 14:33:18 -0400 Subject: [PATCH] Update CodeQL CLI manual (#52486) Co-authored-by: Angela P Wen Co-authored-by: Sunbrye Ly <56200261+sunbrye@users.noreply.github.com> --- .../codeql-cli-manual/generate-query-help.md | 9 +- .../codeql-cli/codeql-cli-manual/index.md | 1 + .../codeql-cli-manual/resolve-packs.md | 165 ++++++++++++++++++ .../codeql-cli-manual/resolve-qlpacks.md | 8 +- 4 files changed, 176 insertions(+), 7 deletions(-) create mode 100644 content/code-security/codeql-cli/codeql-cli-manual/resolve-packs.md diff --git a/content/code-security/codeql-cli/codeql-cli-manual/generate-query-help.md b/content/code-security/codeql-cli/codeql-cli-manual/generate-query-help.md index 58ca95316ef9..1ffeffeada5f 100644 --- a/content/code-security/codeql-cli/codeql-cli-manual/generate-query-help.md +++ b/content/code-security/codeql-cli/codeql-cli-manual/generate-query-help.md @@ -24,7 +24,7 @@ redirect_from: ## Synopsis ```shell copy -codeql generate query-help --format= [--output=] ... -- ... +codeql generate query-help --format= [--output=] ... -- ... ``` ## Description @@ -35,14 +35,15 @@ Generate end-user query help from .qhelp files. ### Primary Options -#### `...` +#### `...` \[Mandatory] Query help files to render. Each argument is one of: * A .qhelp file to render. -* A .ql file with a corresponding .qhelp file to render. +* A .md file to render. +* A .ql file with a corresponding .qhelp or .md file to render. * A directory that will be searched recursively for .ql files with - corresponding .qhelp files. + corresponding .qhelp or .md files. * A .qls file that defines a particular set of queries. * The basename of a "well-known" .qls file exported by one of the installed QL packs. diff --git a/content/code-security/codeql-cli/codeql-cli-manual/index.md b/content/code-security/codeql-cli/codeql-cli-manual/index.md index 3e27e5a1b32a..3fba7fe6156d 100644 --- a/content/code-security/codeql-cli/codeql-cli-manual/index.md +++ b/content/code-security/codeql-cli/codeql-cli-manual/index.md @@ -83,6 +83,7 @@ children: - /resolve-library-path - /resolve-metadata - /resolve-ml-models + - /resolve-packs - /resolve-qlpacks - /resolve-qlref - /resolve-queries diff --git a/content/code-security/codeql-cli/codeql-cli-manual/resolve-packs.md b/content/code-security/codeql-cli/codeql-cli-manual/resolve-packs.md new file mode 100644 index 000000000000..f3ebe2be266b --- /dev/null +++ b/content/code-security/codeql-cli/codeql-cli-manual/resolve-packs.md @@ -0,0 +1,165 @@ +--- +title: resolve packs +intro: Display a list of available CodeQL packs and their locations. +versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 + fpt: '*' + ghec: '*' + ghes: '*' +topics: + - Advanced Security + - Code scanning + - CodeQL +type: reference +product: '{% data reusables.gated-features.codeql %}' +autogenerated: codeql-cli +--- + + + +{% data reusables.codeql-cli.man-pages-version-note %} + +## Synopsis + +```shell copy +codeql resolve packs ... +``` + +## Description + +Display a list of available CodeQL packs and their locations. + +This command shows all of the locations searched for CodeQL packs, based +on the specified search path options. For each searched location, it +lists the packs that were found in that location. + +## Options + +### Primary Options + +#### `--search-path=[:...]` + +A list of directories under which QL packs may be found. Each directory +can either be a QL pack (or bundle of packs containing a +`.codeqlmanifest.json` file at the root) or the immediate parent of one +or more such directories. + +If the path contains more than one directory, their order defines +precedence between them: when a pack name that must be resolved is +matched in more than one of the directory trees, the one given first +wins. + +Pointing this at a checkout of the open-source CodeQL repository ought +to work when querying one of the languages that live there. + +If you have checked out the CodeQL repository as a sibling of the +unpacked CodeQL toolchain, you don't need to give this option; such +sibling directories will always be searched for QL packs that cannot be +found otherwise. (If this default does not work, it is strongly +recommended to set up `--search-path` once and for all in a per-user +configuration file). + +(Note: On Windows the path separator is `;`). + +#### `--additional-packs=[:...]` + +If this list of directories is given, they will be searched for packs +before the ones in `--search-path`. The order between these doesn't +matter; it is an error if a pack name is found in two different places +through this list. + +This is useful if you're temporarily developing a new version of a pack +that also appears in the default path. On the other hand, it is _not +recommended_ to override this option in a config file; some internal +actions will add this option on the fly, overriding any configured +value. + +(Note: On Windows the path separator is `;`). + +#### `--kind=` + +Specifies which kind of packages to return. Options are: `query`, +`library`, `extension`, and `all` (default). + +Note that extension packs are a kind of library pack and are included +when the kind is `library`. + +#### `--format=` + +Select output format, either `text` _(default)_ or `json`. + +#### `--[no-]show-hidden-packs` + +Show which packs were hidden by a pack found earlier in the search. + +### Options for configuring the CodeQL package manager + +#### `--registries-auth-stdin` + +Authenticate to GitHub Enterprise Server Container registries by passing +a comma-separated list of \=\ pairs. + +For example, you can pass +`https://containers.GHEHOSTNAME1/v2/=TOKEN1,https://containers.GHEHOSTNAME2/v2/=TOKEN2` +to authenticate to two GitHub Enterprise Server instances. + +This overrides the CODEQL\_REGISTRIES\_AUTH and GITHUB\_TOKEN environment +variables. If you only need to authenticate to the github.com Container +registry, you can instead authenticate using the simpler +`--github-auth-stdin` option. + +#### `--github-auth-stdin` + +Authenticate to the github.com Container registry by passing a +github.com GitHub Apps token or personal access token via standard +input. + +To authenticate to GitHub Enterprise Server Container registries, pass +`--registries-auth-stdin` or use the CODEQL\_REGISTRIES\_AUTH environment +variable. + +This overrides the GITHUB\_TOKEN environment variable. + +### Common options + +#### `-h, --help` + +Show this help text. + +#### `-J=` + +\[Advanced] Give option to the JVM running the command. + +(Beware that options containing spaces will not be handled correctly.) + +#### `-v, --verbose` + +Incrementally increase the number of progress messages printed. + +#### `-q, --quiet` + +Incrementally decrease the number of progress messages printed. + +#### `--verbosity=` + +\[Advanced] Explicitly set the verbosity level to one of errors, +warnings, progress, progress+, progress++, progress+++. Overrides `-v` +and `-q`. + +#### `--logdir=` + +\[Advanced] Write detailed logs to one or more files in the given +directory, with generated names that include timestamps and the name of +the running subcommand. + +(To write a log file with a name you have full control over, instead +give `--log-to-stderr` and redirect stderr as desired.) + +#### `--common-caches=` + +\[Advanced] Controls the location of cached data on disk that will +persist between several runs of the CLI, such as downloaded QL packs and +compiled query plans. If not set explicitly, this defaults to a +directory named `.codeql` in the user's home directory; it will be +created if it doesn't already exist. + +Available since `v2.15.2`. diff --git a/content/code-security/codeql-cli/codeql-cli-manual/resolve-qlpacks.md b/content/code-security/codeql-cli/codeql-cli-manual/resolve-qlpacks.md index 79c423547535..bd7a33090a69 100644 --- a/content/code-security/codeql-cli/codeql-cli-manual/resolve-qlpacks.md +++ b/content/code-security/codeql-cli/codeql-cli-manual/resolve-qlpacks.md @@ -29,10 +29,12 @@ codeql resolve qlpacks ... ## Description -Create a list of installed QL packs and their locations. +\[Deprecated] Create a list of installed QL packs and their locations. -This plumbing command creates a list of QL packs that can be resolved -given the configured (or given) search path. +This command is deprecated. Use the [codeql resolve packs](/code-security/codeql-cli/codeql-cli-manual/resolve-packs) command instead. + +This command creates a list of QL packs that can be resolved given the +configured (or given) search path. When run with JSON output selected, it can report multiple locations for each pack name. When that happens, it means that the pack has