Movatterモバイル変換

[0]ホーム
URL:

CodeQL documentation
CodeQL resources

CodeQL library for JavaScript

When you’re analyzing a JavaScript program, you can make use of the large collection of classes in the CodeQL library for JavaScript.

Overview

There is an extensive CodeQL library for analyzing JavaScript code. The classes in this library present the data from a CodeQL database in an object-oriented form and provide abstractions and predicates to help you with common analysis tasks.

The library is implemented as a set of QL modules, that is, files with the extension.qll. The modulejavascript.qll imports most other standard library modules, so you can include the complete library by beginning your query with:

importjavascript

The rest of this tutorial briefly summarizes the most important classes and predicates provided by this library, including references to thedetailed API documentation where applicable.

Introducing the library

The CodeQL library for JavaScript presents information about JavaScript source code at different levels:

  • Textual — classes that represent source code as unstructured text files

  • Lexical — classes that represent source code as a series of tokens and comments

  • Syntactic — classes that represent source code as an abstract syntax tree

  • Name binding — classes that represent scopes and variables

  • Control flow — classes that represent the flow of control during execution

  • Data flow — classes that you can use to reason about data flow in JavaScript source code

  • Type inference — classes that you can use to approximate types for JavaScript expressions and variables

  • Call graph — classes that represent the caller-callee relationship between functions

  • Inter-procedural data flow — classes that you can use to define inter-procedural data flow and taint tracking analyses

  • Frameworks — classes that represent source code entities that have a special meaning to JavaScript tools and frameworks

Note that representations above the textual level (for example the lexical representation or the flow graphs) are only available for JavaScript code that does not contain fatal syntax errors. For code with such errors, the only information available is at the textual level, as well as information about the errors themselves.

Additionally, there is library support for working with HTML documents, JSON, and YAML data, JSDoc comments, and regular expressions.

Textual level

At its most basic level, a JavaScript code base can simply be viewed as a collection of files organized into folders, where each file is composed of zero or more lines of text.

Note that the textual content of a program is not included in the CodeQL database unless you specifically request it during extraction.

Files and folders

In the CodeQL libraries, files are represented as entities of classFile, and folders as entities of classFolder, both of which are subclasses of classContainer.

ClassContainer provides the following member predicates:

  • Container.getParentContainer() returns the parent folder of the file or folder.

  • Container.getAFile() returns a file within the folder.

  • Container.getAFolder() returns a folder nested within the folder.

Note that whilegetAFile andgetAFolder are declared on classContainer, they currently only have results forFolders.

Both files and folders have paths, which can be accessed by the predicateContainer.getAbsolutePath(). For example, iff represents a file with the path/home/user/project/src/index.js, thenf.getAbsolutePath() evaluates to the string"/home/user/project/src/index.js", whilef.getParentContainer().getAbsolutePath() returns"/home/user/project/src".

These paths are absolute file system paths. If you want to obtain the path of a file relative to the source location in the CodeQL database, useContainer.getRelativePath() instead. Note, however, that a database may contain files that are not located underneath the source location; for such files,getRelativePath() will not return anything.

The following member predicates of classContainer provide more information about the name of a file or folder:

  • Container.getBaseName() returns the base name of a file or folder, not including its parent folder, but including its extension. In the above example,f.getBaseName() would return the string"index.js".

  • Container.getStem() is similar toContainer.getBaseName(), but it doesnot include the file extension; sof.getStem() returns"index".

  • Container.getExtension() returns the file extension, not including the dot; sof.getExtension() returns"js".

For example, the following query computes, for each folder, the number of JavaScript files (that is, files with extensionjs) contained in the folder:

importjavascriptfromFolderdselectd.getRelativePath(),count(Filef|f=d.getAFile()andf.getExtension()="js")

When you run the query on most projects, the results include folders that contain files with ajs extension and folders that don’t.

Locations

Most entities in a CodeQL database have an associated source location. Locations are identified by five pieces of information: a file, a start line, a start column, an end line, and an end column. Line and column counts are 1-based (so the first character of a file is at line 1, column 1), and the end position is inclusive.

All entities associated with a source location belong to the classLocatable. The location itself is modeled by the classLocation and can be accessed through the member predicateLocatable.getLocation(). TheLocation class provides the following member predicates:

  • Location.getFile(),Location.getStartLine(),Location.getStartColumn(),Location.getEndLine(),Location.getEndColumn() return detailed information about the location.

  • Location.getNumLines() returns the number of (whole or partial) lines covered by the location.

  • Location.startsBefore(Location) andLocation.endsAfter(Location) determine whether one location starts before or ends after another location.

  • Location.contains(Location) indicates whether one location completely contains another location;l1.contains(l2) holds if, and only if,l1.startsBefore(l2) andl1.endsAfter(l2).

Lines

Lines of text in files are represented by the classLine. This class offers the following member predicates:

  • Line.getText() returns the text of the line, excluding any terminating newline characters.

  • Line.getTerminator() returns the terminator character(s) of the line. The last line in a file may not have any terminator characters, in which case this predicate does not return anything; otherwise it returns either the two-character string"\r\n" (carriage-return followed by newline), or one of the one-character strings"\n" (newline),"\r" (carriage-return),"\u2028" (Unicode character LINE SEPARATOR),"\u2029" (Unicode character PARAGRAPH SEPARATOR).

Note that, as mentioned above, the textual representation of the program is not included in the CodeQL database by default.

Lexical level

A slightly more structured view of a JavaScript program is provided by the classesToken andComment, which represent tokens and comments, respectively.

Tokens

The most important member predicates of classToken are as follows:

  • Token.getValue() returns the source text of the token.

  • Token.getIndex() returns the index of the token within its enclosing script.

  • Token.getNextToken() andToken.getPreviousToken() navigate between tokens.

TheToken class has nine subclasses, each representing a particular kind of token:

As an example of a query operating entirely on the lexical level, consider the following query, which finds consecutive comma tokens arising from an omitted element in an array expression:

importjavascriptclassCommaTokenextendsPunctuatorToken{CommaToken(){getValue()=","}}fromCommaTokencommawherecomma.getNextToken()instanceofCommaTokenselectcomma,"Omitted array elements are bad style."

If the query returns no results, this pattern isn’t used in the projects that you analyzed.

You can use predicateLocatable.getFirstToken() andLocatable.getLastToken() to access the first and last token (if any) belonging to an element with a source location.

Comments

The classComment and its subclasses represent the different kinds of comments that can occur in JavaScript programs:

The most important member predicates are as follows:

  • Comment.getText() returns the source text of the comment, not including delimiters.

  • Comment.getLine(i) returns theith line of text within the comment (0-based).

  • Comment.getNumLines() returns the number of lines in the comment.

  • Comment.getNextToken() returns the token immediately following a comment. Note that such a token always exists: if a comment appears at the end of a file, its following token is anEOFToken.

As an example of a query using only lexical information, consider the following query for finding HTML comments, which are not a standard ECMAScript feature and should be avoided:

importjavascriptfromHtmlLineCommentcselectc,"Do not use HTML comments."

Syntactic level

The majority of classes in the JavaScript library is concerned with representing a JavaScript program as a collection ofabstract syntax trees (ASTs).

The classASTNode contains all entities representing nodes in the abstract syntax trees and defines generic tree traversal predicates:

  • ASTNode.getChild(i): returns theith child of this AST node.

  • ASTNode.getAChild(): returns any child of this AST node.

  • ASTNode.getParent(): returns the parent node of this AST node, if any.

Note

These predicates should only be used to perform generic AST traversal. To access children of specific AST node types, the specialized predicates introduced below should be used instead. In particular, queries should not rely on the numeric indices of child nodes relative to their parent nodes: these are considered an implementation detail that may change between versions of the library.

Top-levels

From a syntactic point of view, each JavaScript program is composed of one or more top-level code blocks (ortop-levels for short), which are blocks of JavaScript code that do not belong to a larger code block. Top-levels are represented by the classTopLevel and its subclasses:

  • TopLevel

    • Script: a stand-alone file or HTML<script> element

    • CodeInAttribute: a code block originating from an HTML attribute value

      • EventHandlerCode: code from an event handler attribute such asonload

      • JavaScriptURL: code from a URL with the#"https://codeql.github.com/codeql-standard-libraries/javascript/semmle/javascript/AST.qll/type.AST$Externs.html">Externs: a JavaScript file containingexterns definitions

    EveryTopLevel class is contained in aFile class, but a singleFile may contain more than oneTopLevel. To go from aTopLeveltl to itsFile, usetl.getFile(); conversely, for aFilef, predicatef.getATopLevel() returns a top-level contained inf. For every AST node, predicateASTNode.getTopLevel() can be used to find the top-level it belongs to.

    TheTopLevel class additionally provides the following member predicates:

    • TopLevel.getNumberOfLines() returns the total number of lines (including code, comments and whitespace) in the top-level.

    • TopLevel.getNumberOfLinesOfCode() returns the number of lines of code, that is, lines that contain at least one token.

    • TopLevel.getNumberOfLinesOfComments() returns the number of lines containing or belonging to a comment.

    • TopLevel.isMinified() determines whether the top-level contains minified code, using a heuristic based on the average number of statements per line.

    Note

    By default, GitHub code scanning filters out alerts in minified top-levels, since they are often hard to interpret. When you write your own queries in Visual Studio Code, this filtering isnot done automatically, so you may want to explicitly add a condition of the formandnote.getTopLevel().isMinified() or similar to your query to exclude results in minified code.

Statements and expressions

The most important subclasses ofASTNode besidesTopLevel areStmt andExpr, which, together with their subclasses, represent statements and expressions, respectively. This section briefly discusses some of the more important classes and predicates. For a full reference of all the subclasses ofStmt andExpr and their API, seeStmt.qll andExpr.qll.

  • Stmt: useStmt.getContainer() to access the innermost function or top-level in which the statement is contained.

    • ControlStmt: a statement that controls the execution of other statements, that is, a conditional, loop,try orwith statement; useControlStmt.getAControlledStmt() to access the statements that it controls.

      • IfStmt: anif statement; useIfStmt.getCondition(),IfStmt.getThen() andIfStmt.getElse() to access its condition expression, “then” branch and “else” branch, respectively.

      • LoopStmt: a loop; useLoop.getBody() andLoop.getTest() to access its body and its test expression, respectively.

        • WhileStmt,DoWhileStmt: a “while” or “do-while” loop, respectively.

        • ForStmt: a “for” statement; useForStmt.getInit() andForStmt.getUpdate() to access the init and update expressions, respectively.

        • EnhancedForLoop: a “for-in” or “for-of” loop; useEnhancedForLoop.getIterator() to access the loop iterator (which may be a expression or variable declaration), andEnhancedForLoop.getIterationDomain() to access the expression being iterated over.

      • WithStmt: a “with” statement; useWithStmt.getExpr() andWithStmt.getBody() to access the controlling expression and the body of the with statement, respectively.

      • SwitchStmt: a switch statement; useSwitchStmt.getExpr() to access the expression on which the statement switches; useSwitchStmt.getCase(int) andSwitchStmt.getACase() to access individual switch cases; each case is modeled by an entity of classCase, whose member predicatesCase.getExpr() andCase.getBodyStmt(int) provide access to the expression checked by the switch case (which is undefined fordefault), and its body.

      • TryStmt: a “try” statement; useTryStmt.getBody(),TryStmt.getCatchClause() andTryStmt.getFinally to access its body, “catch” clause and “finally” block, respectively.

    • BlockStmt: a block of statements; useBlockStmt.getStmt(int) to access the individual statements in the block.

    • ExprStmt: an expression statement; useExprStmt.getExpr() to access the expression itself.

    • JumpStmt: a statement that disrupts structured control flow, that is, one ofbreak,continue,return andthrow; use predicateJumpStmt.getTarget() to determine the target of the jump, which is either a statement or (forreturn and uncaughtthrow statements) the enclosing function.

      • BreakStmt: a “break” statement; useBreakStmt.getLabel() to access its (optional) target label.

      • ContinueStmt: a “continue” statement; useContinueStmt.getLabel() to access its (optional) target label.

      • ReturnStmt: a “return” statement; useReturnStmt.getExpr() to access its (optional) result expression.

      • ThrowStmt: a “throw” statement; useThrowStmt.getExpr() to access its thrown expression.

    • FunctionDeclStmt: a function declaration statement; see below for available member predicates.

    • ClassDeclStmt: a class declaration statement; see below for available member predicates.

    • DeclStmt: a declaration statement containing one or more declarators which can be accessed by predicateDeclStmt.getDeclarator(int).

  • Expr: useExpr.getEnclosingStmt() to obtain the innermost statement to which this expression belongs;Expr.isPure() determines whether the expression is side-effect-free.

    • Identifier: an identifier; useIdentifier.getName() to obtain its name.

    • Literal: a literal value; useLiteral.getValue() to obtain a string representation of its value, andLiteral.getRawValue() to obtain its raw source text (including surrounding quotes for string literals).

    • ThisExpr: a “this” expression.

    • SuperExpr: a “super” expression.

    • ArrayExpr: an array expression; useArrayExpr.getElement(i) to obtain theith element expression, andArrayExpr.elementIsOmitted(i) to check whether theith element is omitted.

    • ObjectExpr: an object expression; useObjectExpr.getProperty(i) to obtain theith property in the object expression; properties are modeled by classProperty, which is described in more detail below.

    • FunctionExpr: a function expression; see below for available member predicates.

    • ArrowFunctionExpr: an ECMAScript 2015-style arrow function expression; see below for available member predicates.

    • ClassExpr: a class expression; see below for available member predicates.

    • ParExpr: a parenthesized expression; useParExpr.getExpression() to obtain the operand expression; for any expression,Expr.stripParens() can be used to recursively strip off any parentheses

    • SeqExpr: a sequence of two or more expressions connected by the comma operator; useSeqExpr.getOperand(i) to obtain theith sub-expression.

    • ConditionalExpr: a ternary conditional expression; member predicatesConditionalExpr.getCondition(),ConditionalExpr.getConsequent() andConditionalExpr.getAlternate() provide access to the condition expression, the “then” expression and the “else” expression, respectively.

    • InvokeExpr: a function call or a “new” expression; useInvokeExpr.getCallee() to obtain the expression specifying the function to be called, andInvokeExpr.getArgument(i) to obtain theith argument expression.

      • CallExpr: a function call.

      • NewExpr: a “new” expression.

      • MethodCallExpr: a function call whose callee expression is a property access; useMethodCallExpr.getReceiver to access the receiver expression of the method call, andMethodCallExpr.getMethodName() to get the method name (if it can be determined statically).

    • PropAccess: a property access, that is, either a “dot” expression of the forme.f or an index expression of the forme[p]; usePropAccess.getBase() to obtain the base expression on which the property is accessed (e in the example), andPropAccess.getPropertyName() to determine the name of the accessed property; if the name cannot be statically determined,getPropertyName() does not return any value.

      • DotExpr: a “dot” expression.

      • IndexExpr: an index expression (also known as computed property access).

    • UnaryExpr: a unary expression; useUnaryExpr.getOperand() to obtain the operand expression.

    • BinaryExpr: a binary expression; useBinaryExpr.getLeftOperand() andBinaryExpr.getRightOperand() to access the operand expressions.

    • Assignment: assignment expressions, either simple or compound; useAssignment.getLhs() andAssignment.getRhs() to access the left- and right-hand side, respectively.

    • UpdateExpr: an increment or decrement expression; useUpdateExpr.getOperand() to obtain the operand expression.

    • YieldExpr: a “yield” expression; useYieldExpr.getOperand() to access the (optional) operand expression; useYieldExpr.isDelegating() to check whether this is a delegatingyield*.

    • TemplateLiteral: an ECMAScript 2015 template literal;TemplateLiteral.getElement(i) returns theith element of the template, which may either be an interpolated expression or a constant template element.

    • TaggedTemplateExpr: an ECMAScript 2015 tagged template literal; useTaggedTemplateExpr.getTag() to access the tagging expression, andTaggedTemplateExpr.getTemplate() to access the template literal being tagged.

    • TemplateElement: a constant template element; as for literals, useTemplateElement.getValue() to obtain the value of the element, andTemplateElement.getRawValue() for its raw value

    • AwaitExpr: an “await” expression; useAwaitExpr.getOperand() to access the operand expression.

Stmt andExpr share a common superclassExprOrStmt which is useful for queries that should operate either on statements or on expressions, but not on any other AST nodes.

As an example of how to use expression AST nodes, here is a query that finds expressions of the forme+f>>g; such expressions should be rewritten as(e+f)>>g to clarify operator precedence:

importjavascriptfromShiftExprshift,AddExpraddwhereadd=shift.getAnOperand()selectadd,"This expression should be bracketed to clarify precedence rules."

Functions

JavaScript provides several ways of defining functions: in ECMAScript 5, there are function declaration statements and function expressions, and ECMAScript 2015 adds arrow function expressions. These different syntactic forms are represented by the classesFunctionDeclStmt (a subclass ofStmt),FunctionExpr (a subclass ofExpr) andArrowFunctionExpr (also a subclass ofExpr), respectively. All three are subclasses ofFunction, which provides common member predicates for accessing function parameters or the function body:

  • Function.getId() returns theIdentifier naming the function, which may not be defined for function expressions.

  • Function.getParameter(i) andFunction.getAParameter() access theith parameter or any parameter, respectively; parameters are modeled by the classParameter, which is a subclass ofBindingPattern (see below).

  • Function.getBody() returns the body of the function, which is usually aStmt, but may be anExpr for arrow function expressions and legacyexpression closures.

As an example, here is a query that finds all expression closures:

importjavascriptfromFunctionExprfewherefe.getBody()instanceofExprselectfe,"Use arrow expressions instead of expression closures."

As another example, this query finds functions that have two parameters that bind the same variable:

importjavascriptfromFunctionfun,Parameterp,Parameterq,inti,intjwherep=fun.getParameter(i)andq=fun.getParameter(j)andi<jandp.getAVariable()=q.getAVariable()selectfun,"This function has two parameters that bind the same variable."

Classes

Classes can be defined either by class declaration statements, represented by the CodeQL classClassDeclStmt (which is a subclass ofStmt), or by class expressions, represented by the CodeQL classClassExpr (which is a subclass ofExpr). Both of these classes are also subclasses ofClassDefinition, which provides common member predicates for accessing the name of a class, its superclass, and its body:

  • ClassDefinition.getIdentifier() returns theIdentifier naming the function, which may not be defined for class expressions.

  • ClassDefinition.getSuperClass() returns theExpr specifying the superclass, which may not be defined.

  • ClassDefinition.getMember(n) returns the definition of membern of this class.

  • ClassDefinition.getMethod(n) restrictsClassDefinition.getMember(n) to methods (as opposed to fields).

  • ClassDefinition.getField(n) restrictsClassDefinition.getMember(n) to fields (as opposed to methods).

  • ClassDefinition.getConstructor() gets the constructor of this class, possibly a synthetic default constructor.

Note that class fields are not a standard language feature yet, so details of their representation may change.

Method definitions are represented by the classMethodDefinition, which (like its counterpartFieldDefinition for fields) is a subclass ofMemberDefinition. That class provides the following important member predicates:

  • MemberDefinition.isStatic(): holds if this is a static member.

  • MemberDefinition.isComputed(): holds if the name of this member is computed at runtime.

  • MemberDefinition.getName(): gets the name of this member if it can be determined statically.

  • MemberDefinition.getInit(): gets the initializer of this field; for methods, the initializer is a function expressions, for fields it may be an arbitrary expression, and may be undefined.

There are three classes for modeling special methods:ConstructorDefinition models constructors, whileGetterMethodDefinition andSetterMethodDefinition model getter and setter methods, respectively.

Declarations and binding patterns

Variables are declared by declaration statements (classDeclStmt), which come in three flavors:var statements (represented by classVarDeclStmt),const statements (represented by classConstDeclStmt), andlet statements (represented by classLetStmt). Every declaration statement has one or more declarators, represented by classVariableDeclarator.

Each declarator consists of a binding pattern, returned by predicateVariableDeclarator.getBindingPattern(), and an optional initializing expression, returned byVariableDeclarator.getInit().

Often, the binding pattern is a simple identifier, as invarx=42. In ECMAScript 2015 and later, however, it can also be a more complex destructuring pattern, as invar[x,y]=arr.

The various kinds of binding patterns are represented by classBindingPattern and its subclasses:

  • VarRef: a simple identifier in an l-value position, for example thex invarx or inx=42

  • Parameter: a function or catch clause parameter

  • ArrayPattern: an array pattern, for example, the left-hand side of[x,y]=arr

  • ObjectPattern: an object pattern, for example, the left-hand side of{x,y:z}=o

Here is an example of a query to find declaration statements that declare the same variable more than once, excluding results in minified code:

importjavascriptfromDeclStmtds,VariableDeclaratord1,VariableDeclaratord2,Variablev,inti,intjwhered1=ds.getDecl(i)andd2=ds.getDecl(j)andi<jandv=d1.getBindingPattern().getAVariable()andv=d2.getBindingPattern().getAVariable()andnotds.getTopLevel().isMinified()selectds,"Variable "+v.getName()+" is declared both $@ and $@.",d1,"here",d2,"here"

This is not a common problem, so you may not find any results in your own projects.

Notice the use ofnot...isMinified() here and in the next few queries. This excludes any results found in minified code. If you deleteandnotds.getTopLevel().isMinified() and re-run the query, two results in minified code in themeteor/meteor project are reported.

Properties

Properties in object literals are represented by classProperty, which is also a subclass ofASTNode, but neither ofExpr nor ofStmt.

ClassProperty has two subclassesValueProperty andPropertyAccessor, which represent, respectively, normal value properties and getter/setter properties. ClassPropertyAccessor, in turn, has two subclassesPropertyGetter andPropertySetter representing getters and setters, respectively.

The predicatesProperty.getName() andProperty.getInit() provide access to the defined property’s name and its initial value. ForPropertyAccessor and its subclasses,getInit() is overloaded to return the getter/setter function.

As an example of a query involving properties, consider the following query that flags object expressions containing two identically named properties, excluding results in minified code:

importjavascriptfromObjectExproe,Propertyp1,Propertyp2,inti,intjwherep1=oe.getProperty(i)andp2=oe.getProperty(j)andi<jandp1.getName()=p2.getName()andnotoe.getTopLevel().isMinified()selectoe,"Property "+p1.getName()+" is defined both $@ and $@.",p1,"here",p2,"here"

Modules

The JavaScript library has support for working with ECMAScript 2015 modules, as well as legacy CommonJS modules (still commonly employed by Node.js code bases) and AMD-style modules. The classesES2015Module,NodeModule, andAMDModule represent these three types of modules, and all three extend the common superclassModule.

The most important member predicates defined byModule are:

  • Module.getName(): gets the name of the module, which is just the stem (that is, the basename without extension) of the enclosing file.

  • Module.getAnImportedModule(): gets another module that is imported (throughimport orrequire) by this module.

  • Module.getAnExportedSymbol(): gets the name of a symbol that this module exports.

Moreover, there is a classImport that models both ECMAScript 2015-styleimport declarations and CommonJS/AMD-stylerequire calls; its member predicateImport.getImportedModule provides access to the module the import refers to, if it can be determined statically.

Name binding

Name binding is modeled in the JavaScript libraries using four concepts:scopes,variables,variable declarations, andvariable accesses, represented by the classesScope,Variable,VarDecl andVarAccess, respectively.

Scopes

In ECMAScript 5, there are three kinds of scopes: the global scope (one per program), function scopes (one per function), and catch clause scopes (one percatch clause). These three kinds of scopes are represented by the classesGlobalScope,FunctionScope andCatchScope. ECMAScript 2015 adds block scopes forlet-bound variables, which are also represented by classScope, class expression scopes (ClassExprScope),and module scopes (ModuleScope).

ClassScope provides the following API:

  • Scope.getScopeElement() returns the AST node inducing this scope; undefined forGlobalScope.

  • Scope.getOuterScope() returns the lexically enclosing scope of this scope.

  • Scope.getAnInnerScope() returns a scope lexically nested inside this scope.

  • Scope.getVariable(name),Scope.getAVariable() return a variable declared (implicitly or explicitly) in this scope.

Variables

TheVariable class models all variables in a JavaScript program, including global variables, local variables, and parameters (both of functions andcatch clauses), whether explicitly declared or not.

It is important not to confuse variables and their declarations: local variables may have more than one declaration, while global variables and the implicitly declared localarguments variable need not have a declaration at all.

Variable declarations and accesses

Variables may be declared by variable declarators, by function declaration statements and expressions, by class declaration statements or expressions, or by parameters of functions andcatch clauses. While these declarations differ in their syntactic form, in each case there is an identifier naming the declared variable. We consider that identifier to be the declaration proper, and assign it the classVarDecl. Identifiers that reference a variable, on the other hand, are given the classVarAccess.

The most important predicates involving variables, their declarations, and their accesses are as follows:

  • Variable.getName(),VarDecl.getName(),VarAccess.getName() return the name of the variable.

  • Variable.getScope() returns the scope to which the variable belongs.

  • Variable.isGlobal(),Variable.isLocal(),Variable.isParameter() determine whether the variable is a global variable, a local variable, or a parameter variable, respectively.

  • Variable.getAnAccess() maps aVariable to allVarAccesses that refer to it.

  • Variable.getADeclaration() maps aVariable to allVarDecls that declare it (of which there may be none, one, or more than one).

  • Variable.isCaptured() determines whether the variable is ever accessed in a scope that is lexically nested within the scope where it is declared.

As an example, consider the following query which finds distinct function declarations that declare the same variable, that is, two conflicting function declarations within the same scope (again excluding minified code):

importjavascriptfromFunctionDeclStmtf,FunctionDeclStmtgwheref!=gandf.getVariable()=g.getVariable()andnotf.getTopLevel().isMinified()andnotg.getTopLevel().isMinified()selectf,g

Some projects declare conflicting functions of the same name and rely on platform-specific behavior to disambiguate the two declarations.

Control flow

A different program representation in terms of intraprocedural control flow graphs (CFGs) is provided by the classes in libraryCFG.qll.

ClassControlFlowNode represents a single node in the control flow graph, which is either an expression, a statement, or a synthetic control flow node. Note thatExpr andStmt do not inherit fromControlFlowNode at the CodeQL level, although their entity types are compatible, so you can explicitly cast from one to the other if you need to map between the AST-based and the CFG-based program representations.

There are two kinds of synthetic control flow nodes: entry nodes (classControlFlowEntryNode), which represent the beginning of a top-level or function, and exit nodes (classControlFlowExitNode), which represent their end. They do not correspond to any AST nodes, but simply serve as the unique entry point and exit point of a control flow graph. Entry and exit nodes can be accessed through the predicatesStmtContainer.getEntry() andStmtContainer.getExit().

Most, but not all, top-levels and functions have another distinguished CFG node, thestart node. This is the CFG node at which execution begins. Unlike the entry node, which is a synthetic construct, the start node corresponds to an actual program element: for top-levels, it is the first CFG node of the first statement; for functions, it is the CFG node corresponding to their first parameter or, if there are no parameters, the first CFG node of the body. Empty top-levels do not have a start node.

For most purposes, using start nodes is preferable to using entry nodes.

The structure of the control flow graph is reflected in the member predicates ofControlFlowNode:

  • ControlFlowNode.getASuccessor() returns aControlFlowNode that is a successor of thisControlFlowNode in the control flow graph.

  • ControlFlowNode.getAPredecessor() is the inverse ofgetASuccessor().

  • ControlFlowNode.isBranch() determines whether this node has more than one successor.

  • ControlFlowNode.isJoin() determines whether this node has more than one predecessor.

  • ControlFlowNode.isStart() determines whether this node is a start node.

Many control-flow-based analyses are phrased in terms ofbasic blocks rather than single control flow nodes, where a basic block is a maximal sequence of control flow nodes without branches or joins. The classBasicBlock fromBasicBlocks.qll represents all such basic blocks. Similar toControlFlowNode, it provides member predicatesgetASuccessor() andgetAPredecessor() to navigate the control flow graph at the level of basic blocks, and member predicatesgetANode(),getNode(int),getFirstNode() andgetLastNode() to access individual control flow nodes within a basic block. The predicateFunction.getEntryBB() returns the entry basic block in a function, that is, the basic block containing the function’s entry node. Similarly,Function.getStartBB() provides access to the start basic block, which contains the function’s start node. As for CFG nodes,getStartBB() should normally be preferred overgetEntryBB().

As an example of an analysis using basic blocks,BasicBlock.isLiveAtEntry(v,u) determines whether variablev islive at the entry of the given basic block, and if so bindsu to a use ofv that refers to its value at the entry. We can use it to find global variables that are used in a function where they are not live (that is, every read of the variable is preceded by a write), suggesting that the variable was meant to be declared as a local variable instead:

importjavascriptfromFunctionf,GlobalVariablegvwheregv.getAnAccess().getEnclosingFunction()=fandnotf.getStartBB().isLiveAtEntry(gv,_)selectf,"This function uses "+gv+" like a local variable."

Many projects have some variables which look as if they were intended to be local.

Data flow

Definitions and uses

LibraryDefUse.qll provides classes and predicates to determinedef-use relationships between definitions and uses of variables.

ClassesVarDef andVarUse contain all expressions that define and use a variable, respectively. For the former, you can use predicateVarDef.getAVariable() to find out which variables are defined by a given variable definition (recall that destructuring assignments in ECMAScript 2015 define several variables at the same time). Similarly, predicateVarUse.getVariable() returns the (single) variable being accessed by a variable use.

The def-use information itself is provided by predicateVarUse.getADef(), that connects a use of a variable to a definition of the same variable, where the definition may reach the use.

As an example, the following query finds definitions of local variables that are not used anywhere; that is, the variable is either not referenced at all after the definition, or its value is overwritten:

importjavascriptfromVarDefdef,LocalVariablevwherev=def.getAVariable()andnotexists(VarUseuse|def=use.getADef())selectdef,"Dead store of local variable."

SSA

A more fine-grained representation of a program’s data flow based onStatic Simple Assignment Form (SSA) is provided by the librarysemmle.javascript.SSA.

In SSA form, each use of a local variable has exactly one (SSA) definition that reaches it. SSA definitions are represented by classSsaDefinition. They are not AST nodes, since not every SSA definition corresponds to an explicit element in the source code.

Altogether, there are five kinds of SSA definitions:

  1. Explicit definitions (SsaExplicitDefinition): these simply wrap aVarDef, that is, a definition likex=1 appearing explicitly in the source code.

  2. Implicit initializations (SsaImplicitInit): these represent the implicit initialization of local variables withundefined at the beginning of their scope.

  3. Phi nodes (SsaPhiNode): these are pseudo-definitions that merge two or more SSA definitions where necessary; see the Wikipedia page linked to above for an explanation.

  4. Variable captures (SsaVariableCapture): these are pseudo-definitions appearing at places in the code where the value of a captured variable may change without there being an explicit assignment, for example due to a function call.

  5. Refinement nodes (SsaRefinementNode): these are pseudo-definitions appearing at places in the code where something becomes known about a variable; for example, a conditionalif(x===null) induces a refinement node at the beginning of its “then” branch recording the fact thatx is known to benull there. (In the literature, these are sometimes known as “pi nodes.”)

Data flow nodes

Moving beyond just variable definitions and uses, librarysemmle.javascript.dataflow.DataFlow provides a representation of the program as a data flow graph. Its nodes are values of classDataFlow::Node, which has two subclassesValueNode andSsaDefinitionNode. Nodes of the former kind wrap an expression or a statement that is considered to produce a value (specifically, a function or class declaration statement, or a TypeScript namespace or enum declaration). Nodes of the latter kind wrap SSA definitions.

You can use the predicateDataFlow::valueNode to convert an expression, function or class into its correspondingValueNode, and similarlyDataFlow::ssaDefinitionNode to map an SSA definition to its correspondingSsaDefinitionNode.

There is also an auxiliary predicateDataFlow::parameterNode that maps a parameter to its corresponding data flow node. (This is really just a convenience wrapper aroundDataFlow::ssaDefinitionNode, since parameters are also considered to be SSA definitions.)

Going in the other direction, there is a predicateValueNode.getAstNode() for mapping fromValueNodes toASTNodes, andSsaDefinitionNode.getSsaVariable() for mapping fromSsaDefinitionNodes toSsaVariables. There is also a utility predicateNode.asExpr() that gets the underlying expression for aValueNode, and is undefined for all nodes that do not correspond to an expression. (Note in particular that this predicate is not defined forValueNodes wrapping function or class declaration statements!)

You can use the predicateDataFlow::Node.getAPredecessor() to find other data flow nodes from which values may flow into this node, andgetASuccessor for the other direction.

For example, here is a query that finds all invocations of a method calledsend on a value that comes from a parameter namedres, indicating that it is perhaps sending an HTTP response:

importjavascriptfromSimpleParameterres,DataFlow::NoderesNode,MethodCallExprsendwhereres.getName()="res"andresNode=DataFlow::parameterNode(res)andresNode.getASuccessor+()=DataFlow::valueNode(send.getReceiver())andsend.getMethodName()="send"selectsend

Note that the data flow modeling in this library is intraprocedural, that is, flow across function calls and returns isnot modeled. Likewise, flow through object properties and global variables is not modeled.

Type inference

The librarysemmle.javascript.dataflow.TypeInference implements a simple type inference for JavaScript based on intraprocedural, heap-insensitive flow analysis. Basically, the inference algorithm approximates the possible concrete runtime values of variables and expressions as sets of abstract values (represented by the classAbstractValue), each of which stands for a set of concrete values.

For example, there is an abstract value representing all non-zero numbers, and another representing all non-empty strings except for those that can be converted to a number. Both of these abstract values are fairly coarse approximations that represent very large sets of concrete values.

Other abstract values are more precise, to the point where they represent single concrete values: for example, there is an abstract value representing the concretenull value, and another representing the number zero.

There is a special group of abstract values calledindefinite abstract values that represent all concrete values. The analysis uses these to handle expressions for which it cannot infer a more precise value, such as function parameters (as mentioned above, the analysis is intraprocedural and hence does not model argument passing) or property reads (the analysis does not model property values either).

Each indefinite abstract value is associated with a string value describing the cause of imprecision. In the above examples, the indefinite value for the parameter would have cause"call", while the indefinite value for the property would have cause"heap".

To check whether an abstract value is indefinite, you can use theisIndefinite member predicate. Its single argument describes the cause of imprecision.

Each abstract value has one or more associated types (CodeQL classInferredType corresponding roughly to the type tags computed by thetypeof operator. The types arenull,undefined,boolean,number,string,function,class,date andobject.

To access the results of the type inference, use classDataFlow::AnalyzedNode: anyDataFlow::Node can be cast to this class, and additionally there is a convenience predicateExpr::analyze that maps expressions directly to their correspondingAnalyzedNodes.

Once you have anAnalyzedNode, you can use predicateAnalyzedNode.getAValue() to access the abstract values inferred for it, andgetAType() to get the inferred types.

For example, here is a query that looks fornull checks on expressions that cannot, in fact, be null:

importjavascriptfromStrictEqualityTesteq,DataFlow::AnalyzedNodend,NullLiteralnullwhereeq.hasOperands(nd.asExpr(),null)andnotnd.getAValue().isIndefinite(_)andnotnd.getAValue()instanceofAbstractNullselecteq,"Spurious null check."

To paraphrase, the query looks for equality testseq where one operand is anull literal and the other some expression that we convert to anAnalyzedNode. If the type inference results for that node are precise (that is, none of the inferred values is indefinite) and (the abstract representation of)null is not among them, we flageq.

You can add custom type inference rules by defining new subclasses ofDataFlow::AnalyzedNode and overridinggetAValue. You can also introduce new abstract values by extending the abstract classCustomAbstractValueTag, which is a subclass ofstring: each string belonging to that class induces a corresponding abstract value of typeCustomAbstractValue. You can use the predicateCustomAbstractValue.getTag() to map from the abstract value to its tag. By implementing the abstract predicates of classCustomAbstractValueTag you can define the semantics of your custom abstract values, such as what primitive value they coerce to and what type they have.

Call graph

The JavaScript library implements a simplecall graph construction algorithm to statically approximate the possible call targets of function calls andnew expressions. Due to the dynamically typed nature of JavaScript and its support for higher-order functions and reflective language features, building static call graphs is quite difficult. Simple call graph algorithms tend to be incomplete, that is, they often fail to resolve all possible call targets. More sophisticated algorithms can suffer from the opposite problem of imprecision, that is, they may infer many spurious call targets.

The call graph is represented by the member predicategetACallee() of classDataFlow::InvokeNode, which computes possible callees of the given invocation, that is, functions that may at runtime be invoked by this expression.

Furthermore, there are three member predicates that indicate the quality of the callee information for this invocation:

  • DataFlow::InvokeNode.isImprecise(): holds for invocations where the call graph builder might infer spurious call targets.

  • DataFlow::InvokeNode.isIncomplete(): holds for invocations where the call graph builder might fail to infer possible call targets.

  • DataFlow::InvokeNode.isUncertain(): holds if eitherisImprecise() orisIncomplete() holds.

As an example of a call-graph-based query, here is a query to find invocations for which the call graph builder could not find any callees, despite the analysis being complete for this invocation:

importjavascriptfromDataFlow::InvokeNodeinvkwherenotinvk.isIncomplete()andnotexists(invk.getACallee())selectinvk,"Unable to find a callee for this invocation."

Inter-procedural data flow

The data flow graph-based analyses described so far are all intraprocedural: they do not take flow from function arguments to parameters or from areturn to the function’s caller into account. The data flow library also provides a framework for constructing custom inter-procedural analyses.

We distinguish here between data flow proper, andtaint tracking: the latter not only considers value-preserving flow (such as from variable definitions to uses), but also cases where one value influences (“taints”) another without determining it entirely. For example, in the assignments2=s1.substring(i), the value ofs1 influences the value ofs2, becauses2 is assigned a substring ofs1. In general,s2 will not be assigneds1 itself, so there is no data flow froms1 tos2, buts1 still taintss2.

It is a common pattern that we wish to specify data flow or taint analysis in terms of itssources (where flow starts),sinks (where it should be tracked), andbarriers (also calledsanitizers) where flow is interrupted. Sanitizers they are very common in security analyses: for example, an analysis that tracks the flow of untrusted user input into, say, a SQL query has to keep track of code that validates the input, thereby making it safe to use. Such a validation step is an example of a sanitizer.

A module implementing the signatureDataFlow::ConfigSig may specify a data flow or taint analysis by implementing the following predicates:

  • isSource(DataFlow::Nodend) selects all nodesnd from where flow tracking starts.

  • isSink(DataFlow::Nodend) selects all nodesnd to which the flow is tracked.

  • isBarrier(DataFlow::Nodend) selects all nodesnd that act as a barrier/sanitizer for data flow.

  • isAdditionalFlowStep(DataFlow::Nodesrc,DataFlow::Nodetrg) allows specifying custom additional flow steps for this analysis.

Such a module can be passed toDataFlow::Global<...>. This will produce a module with aflow predicate that performs the actual flow tracking, starting at a source and looking for flow to a sink that does not pass through a barrier node.

For example, suppose that we are developing an analysis to find hard-coded passwords. We might write a simple query that looks for string constants flowing into variables named"password".

importjavascriptmodulePasswordConfigimplementsDataFlow::ConfigSig{predicateisSource(DataFlow::Nodend){nd.asExpr()instanceofStringLiteral}predicateisSink(DataFlow::Nodend){passwordVarAssign(_,nd)}}predicatepasswordVarAssign(Variablev,DataFlow::Nodend){v.getAnAssignedExpr()=nd.asExpr()andv.getName().toLowerCase()="password"}modulePasswordFlow=DataFlow::Global<PasswordConfig>;

Now we can rephrase our query to usePasswordFlow::flow:

fromDataFlow::Nodesource,DataFlow::Nodesink,VariablevwherePasswordFlow::flow(_,sink)andpasswordVarAssign(v,sink)selectsink,"Password variable "+v+" is assigned a constant string."

Syntax errors

JavaScript code that contains syntax errors cannot usually be analyzed. For such code, the lexical and syntactic representations are not available, and hence no name binding information, call graph or control and data flow. All that is available in this case is a value of classJSParseError representing the syntax error. It provides information about the syntax error location (JSParseError is a subclass ofLocatable) and the error message through predicateJSParseError.getMessage.

Note that for some very simple syntax errors the parser can recover and continue parsing. If this happens, lexical and syntactic information is available in addition to theJSParseError values representing the (recoverable) syntax errors encountered during parsing.

Frameworks

AngularJS

Thesemmle.javascript.frameworks.AngularJS library provides support for working withAngularJS (Angular 1.x) code. Its most important classes are:

HTTP framework libraries

The librarysemmle.javacript.frameworks.HTTP provides classes modeling common concepts from various HTTP frameworks.

Currently supported frameworks areExpress, the standard Node.jshttp andhttps modules,Connect,Koa,Hapi andRestify.

The most important classes include (all in moduleHTTP):

  • ServerDefinition: an expression that creates a new HTTP server.

  • RouteHandler: a callback for handling an HTTP request.

  • RequestExpr: an expression that may contain an HTTP request object.

  • ResponseExpr: an expression that may contain an HTTP response object.

  • HeaderDefinition: an expression that sets one or more HTTP response headers.

  • CookieDefinition: an expression that sets a cookie in an HTTP response.

  • RequestInputAccess: an expression that accesses user-controlled request data.

For each framework library, there is a corresponding CodeQL library (for examplesemmle.javacript.frameworks.Express) that instantiates the above classes for that framework and adds framework-specific classes.

Node.js

Thesemmle.javascript.NodeJS library provides support for working withNode.js modules through the following classes:

  • NodeModule: a top-level that defines a Node.js module; see the section onModules for more information.

  • Require: a call to the specialrequire function that imports a module.

As an example of the use of these classes, here is a query that counts for every module how many other modules it imports:

importjavascriptfromNodeModulemselectm,count(m.getAnImportedModule())

When you analyze a project, for each module you can see how many other modules it imports.

NPM

Thesemmle.javascript.NPM library provides support for working withNPM packages through the following classes:

  • PackageJSON: apackage.json file describing an NPM package; various getter predicates are available for accessing detailed information about the package, which are described in theonline API documentation.

  • BugTrackerInfo,ContributorInfo,RepositoryInfo: these classes model parts of thepackage.json file providing information on bug tracking systems, contributors and repositories.

  • PackageDependencies: models the dependencies of an NPM package; the predicatePackageDependencies.getADependency(pkg,v) bindspkg to the name andv to the version of a package required by apackage.json file.

  • NPMPackage: a subclass ofFolder that models an NPM package; important member predicates include:

    • NPMPackage.getPackageName() returns the name of this package.

    • NPMPackage.getPackageJSON() returns thepackage.json file for this package.

    • NPMPackage.getNodeModulesFolder() returns thenode_modules folder for this package.

    • NPMPackage.getAModule() returns a Node.js module belonging to this package (not including modules in thenode_modules folder).

As an example of the use of these classes, here is a query that identifies unused dependencies, that is, module dependencies that are listed in thepackage.json file, but which are not imported by anyrequire call:

importjavascriptfromNPMPackagepkg,PackageDependenciesdeps,stringnamewheredeps=pkg.getPackageJSON().getDependencies()anddeps.getADependency(name,_)andnotexists(Requirereq|req.getTopLevel()=pkg.getAModule()|name=req.getImportedPath().getValue())selectdeps,"Unused dependency '"+name+"'."

React

Thesemmle.javascript.frameworks.React library provides support for working withReact code through theReactComponent class, which models a React component defined either in the functional style or the class-based style (both ECMAScript 2015 classes and old-styleReact.createClass classes are supported).

Databases

The classSQL::SqlString represents an expression that is interpreted as a SQL command. Currently, we model SQL commands issued through the following npm packages:mysql,pg,pg-pool,sqlite3,mssql andsequelize.

Similarly, the classNoSQL::Query represents an expression that is interpreted as a NoSQL query by themongodb ormongoose package.

Finally, the classDatabaseAccess contains all data flow nodes that perform a database access using any of the packages above.

For example, here is a query to find SQL queries that use string concatenation (instead of a templating-based solution, which is usually safer):

importjavascriptfromSQL::SqlStringsswheressinstanceofAddExprselectss,"Use templating instead of string concatenation."

Miscellaneous

Externs

Thesemmle.javascript.Externs library provides support for working withexterns through the following classes:

  • ExternalDecl: common superclass modeling all different kinds of externs declarations; it defines two member predicates:

    • ExternalDecl.getQualifiedName() returns the fully qualified name of the declared entity.

    • ExternalDecl.getName() returns the unqualified name of the declared entity.

  • ExternalTypedef: a subclass ofExternalDecl representing type declarations; unlike other externs declarations, such declarations do not declare a function or object that is present at runtime, but simply introduce an alias for a type.

  • ExternalVarDecl: a subclass ofExternalDecl representing a variable or function declaration; it defines two member predicates:

    • ExternalVarDecl.getInit() returns the initializer associated with this declaration, if any; this can either be aFunction or anExpr.

    • ExternalVarDecl.getDocumentation() returns the JSDoc comment associated with this declaration.

Variables and functions declared in an externs file are either globals (represented by classExternalGlobalDecl), or members (represented by classExternalMemberDecl).

Members are further subdivided into static members (classExternalStaticMemberDecl) and instance members (classExternalInstanceMemberDecl).

For more details on these and other classes representing externs, seethe API documentation.

HTML

Thesemmle.javascript.HTML library provides support for working with HTML documents. They are represented as a tree ofHTML::Element nodes, each of which may have zero or more attributes represented by classHTML::Attribute.

Similar to the abstract syntax tree representation,HTML::Element has member predicatesgetChild(i) andgetParent() to navigate from an element to itsith child element and its parent element, respectively. Use predicateHTML::Element.getAttribute(i) to get theith attribute of the element, andHTML::Element.getAttributeByName(n) to get the attribute with namen.

ForHTML::Attribute, predicatesgetName() andgetValue() provide access to the attribute’s name and value, respectively.

BothHTML::Element andHTML::Attribute have a predicategetRoot() that gets the rootHTML::Element of the document to which they belong.

JSDoc

Thesemmle.javascript.JSDoc library provides support for working withJSDoc comments. Documentation comments are parsed into an abstract syntax tree representation closely following the format employed by theDoctrine JSDoc parser.

A JSDoc comment as a whole is represented by an entity of classJSDoc, while individual tags are represented by classJSDocTag. Important member predicates of these two classes include:

  • JSDoc.getDescription() returns the descriptive header of the JSDoc comment, if any.

  • JSDoc.getComment() maps theJSDoc entity to its underlyingComment entity.

  • JSDocTag.getATag() returns a tag in this JSDoc comment.

  • JSDocTag.getTitle() returns the title of his tag; for instance, an@param tag has title"param".

  • JSDocTag.getName() returns the name of the parameter or variable documented by this tag.

  • JSDocTag.getType() returns the type of the parameter or variable documented by this tag.

  • JSDocTag.getDescription() returns the description associated with this tag.

Types in JSDoc comments are represented by the classJSDocTypeExpr and its subclasses, which again represent type expressions as abstract syntax trees. Examples of type expressions areJSDocAnyTypeExpr, representing the “any” type*, orJSDocNullTypeExpr, representing the null type.

As an example, here is a query that finds@param tags that do not specify the name of the documented parameter:

importjavascriptfromJSDocTagtwheret.getTitle()="param"andnotexists(t.getName())selectt,"@param tag is missing name."

For full details on these and other classes representing JSDoc comments and type expressions, seethe API documentation.

JSX

Thesemmle.javascript.JSX library provides support for working withJSX code.

Similar to the representation of HTML documents, JSX fragments are modeled as a tree ofJSXElements, each of which may have zero or moreJSXAttributes.

However, unlike HTML, JSX is interleaved with JavaScript, henceJSXElement is a subclass ofExpr. LikeHTML::Element, it has predicatesgetAttribute(i) andgetAttributeByName(n) to look up attributes of a JSX element. Its body elements can be accessed by predicategetABodyElement(); note that the results of this predicate are arbitrary expressions, which may either be furtherJSXElements, or other expressions that are interpolated into the body of the outer element.

JSXAttribute, again not unlikeHTML::Attribute, has predicatesgetName() andgetValue() to access the attribute name and value.

JSON

Thesemmle.javascript.JSON library provides support for working withJSON files that were processed by the JavaScript extractor when building the CodeQL database.

JSON files are modeled as trees of JSON values. Each JSON value is represented by an entity of classJSONValue, which provides the following member predicates:

  • JSONValue.getParent() returns the JSON object or array in which this value occurs.

  • JSONValue.getChild(i) returns theith child of this JSON object or array.

Note thatJSONValue is a subclass ofLocatable, so the usual member predicates ofLocatable can be used to determine the file in which a JSON value appears, and its location within that file.

ClassJSONValue has the following subclasses:

  • JSONPrimitiveValue: a JSON-encoded primitive value; useJSONPrimitiveValue.getValue() to obtain a string representation of the value.

  • JSONArray: a JSON-encoded array; useJSONArray.getElementValue(i) to access theith element of the array.

  • JSONObject: a JSON-encoded object; useJSONObject.getValue(n) to access the value of propertyn of the object.

Regular expressions

Thesemmle.javascript.Regexp library provides support for working with regular expression literals. The syntactic structure of regular expression literals is represented as an abstract syntax tree of regular expression terms, modeled by the classRegExpTerm. Similar toASTNode, classRegExpTerm provides member predicatesgetParent() andgetChild(i) to navigate the structure of the syntax tree.

Various subclasses ofRegExpTerm model different kinds of regular expression constructs and operators; seethe API documentation for details.

YAML

Thesemmle.javascript.YAML library provides support for working withYAML files that were processed by the JavaScript extractor when building the CodeQL database.

YAML files are modeled as trees of YAML nodes. Each YAML node is represented by an entity of classYAMLNode, which provides, among others, the following member predicates:

  • YAMLNode.getParentNode() returns the YAML collection in which this node is syntactically nested.

  • YAMLNode.getChildNode(i) returns theith child node of this node,YAMLNode.getAChildNode() returns any child node of this node.

  • YAMLNode.getTag() returns the tag of this YAML node.

  • YAMLNode.getAnchor() returns the anchor associated with this YAML node, if any.

  • YAMLNode.eval() returns theYAMLValue this YAML node evaluates to after resolving aliases and includes.

The various kinds of scalar values available in YAML are represented by classesYAMLInteger,YAMLFloat,YAMLTimestamp,YAMLBool,YAMLNull andYAMLString. Their common superclass isYAMLScalar, which has a member predicategetValue() to obtain the value of a scalar as astring.

YAMLMapping andYAMLSequence represent mappings and sequences, respectively, and are subclasses ofYAMLCollection.

Alias nodes are represented by classYAMLAliasNode, whileYAMLMergeKey andYAMLInclude represent merge keys and!include directives, respectively.

PredicateYAMLMapping.maps(key,value) models the key-value relation represented by a mapping, taking merge keys into account.

Further reading

[8]ページ先頭
©2009-2025 Movatter.jp