mirror of
https://github.com/github/codeql.git
synced 2025-12-17 09:13:20 +01:00
132 lines
4.5 KiB
ReStructuredText
132 lines
4.5 KiB
ReStructuredText
:tocdepth: 1
|
|
|
|
.. _codeql-glossary:
|
|
|
|
CodeQL glossary
|
|
===============
|
|
|
|
An overview of the technical terms and concepts in CodeQL.
|
|
|
|
.. _bqrs-file:
|
|
|
|
``.bqrs`` file
|
|
--------------
|
|
|
|
A binary query result set (BQRS) file. BQRS is the binary representation of the raw
|
|
result of a query, with the extension ``.bqrs``. A BQRS file can be
|
|
interpreted into meaningful results and related to your source code. For
|
|
example, alert query results are interpreted to display a string at the
|
|
location in the source code where the alert occurs, as specified in the query.
|
|
Similarly, path query results are interpreted as pairs of locations
|
|
(sources and sinks) between which information can flow. These results can be
|
|
exported as a variety of different formats, including SARIF.
|
|
|
|
.. _codeql-database:
|
|
|
|
CodeQL database
|
|
---------------
|
|
|
|
A database (or CodeQL database) is a directory containing:
|
|
|
|
- queryable data, extracted from the code.
|
|
- a source reference, for displaying query results directly in the code.
|
|
- query results.
|
|
- log files generated during database creation, query
|
|
execution, and other operations.
|
|
|
|
.. _dil:
|
|
|
|
DIL
|
|
---
|
|
|
|
DIL stands for Datalog Intermediary Language. It is an intermediate
|
|
representation between QL and relation algebra (RA) that is generated
|
|
during query compilation. DIL is useful for advanced users as an aid
|
|
for debugging query performance.
|
|
The DIL format may change without warning between CLI releases.
|
|
|
|
When you specify the ``--dump-dil`` option for ``codeql query compile``, CodeQL
|
|
prints DIL to standard output for the queries it compiles. You can also
|
|
view results in DIL format when you run queries in VS Code.
|
|
For more information, see ":ref:`Analyzing your projects <viewing-query-results>`" in the CodeQL for VS Code help.
|
|
|
|
.. _extractor:
|
|
|
|
Extractor
|
|
---------
|
|
|
|
An extractor is a tool that produces the relational data and source
|
|
reference for each input file, from which a CodeQL database can be built.
|
|
|
|
.. _codeql-database-schema:
|
|
|
|
QL database schema
|
|
------------------
|
|
|
|
A QL database schema is a file describing the column types and
|
|
extensional relations that make up a raw QL dataset. It is a text file
|
|
with the ``.dbscheme`` extension.
|
|
|
|
The extractor and core CodeQL pack for a language each declare the database
|
|
schema that they use. This defines the database layout they create or
|
|
expect. When you create a CodeQL database, the extractor copies
|
|
its schema into the database. The CLI uses this to check whether the
|
|
CodeQL database is compatible with a particular CodeQL library.
|
|
If they aren't compatible you can use ``database upgrade`` to upgrade
|
|
the schema for the CodeQL database.
|
|
|
|
There is currently no public-facing specification for the syntax of schemas.
|
|
|
|
.. _qlo:
|
|
|
|
``.qlo`` files
|
|
--------------
|
|
|
|
``.qlo`` files are optionally generated during query compilation.
|
|
If you specify the ``--dump-qlo`` option for ``codeql query compile``,
|
|
CodeQL writes ``.qlo`` files for the queries it compiles. They can be used
|
|
as an aid for debugging and performance tuning for advanced users.
|
|
|
|
``.qlo`` is a binary format that represents a compiled
|
|
and optimized query in terms of relational algebra (RA) or the
|
|
intermediate :ref:`DIL <dil>` format. ``.qlo`` files can be expanded to
|
|
readable text using ``codeql query decompile``.
|
|
|
|
The exact details of the ``.qlo`` format may change without warning between CLI releases.
|
|
|
|
.. _sarif-file:
|
|
|
|
SARIF file
|
|
----------
|
|
|
|
Static analysis results interchange format (SARIF) is an output format used for
|
|
sharing static analysis results. For more information, see "`SARIF <https://docs.github.com/en/code-security/codeql-cli/codeql-cli-reference/sarif-output>`__."
|
|
|
|
.. _source-reference:
|
|
|
|
Source reference
|
|
----------------
|
|
|
|
A source reference is a mechanism that allows the retrieval of the
|
|
contents of a source file, given an absolute filename at which that file
|
|
resided during extraction. Specific examples include:
|
|
|
|
- A source archive directory, within which the requested absolute
|
|
filename maps to a UTF8-encoded file.
|
|
- A source archive, typically in ZIP format, which contains the UTF8-encoded
|
|
content of all source files.
|
|
- A source archive repository, typically in ``git`` format, typically bare,
|
|
which contains the UTF8-encoded content of all source files.
|
|
|
|
Source references are typically included in CodeQL databases.
|
|
|
|
.. _trap-file:
|
|
|
|
TRAP file
|
|
---------
|
|
|
|
A TRAP file is a UTF-8 encoded file generated by a CodeQL extractor
|
|
with the extension ``.trap``. To save space, they are usually archived. They
|
|
contain the information that, when interpreted relative to a QL database
|
|
schema, is used to create a QL dataset.
|