Reference: Custom Audit Rule Context Object Methods

14 Reference: Custom Audit Rule Context Object Methods

Use this reference to obtain details about functionality that you can access through an instance of a rule pack manager, rule issue, and rule reporter that you create in custom audit rules.

Audit Rule Classes	Description
RulePack Class Methods	The rule pack manager instance you create provides methods to access rule pack data.
Rule Issue Class Methods	The rule issue instance you create provides methods to set properties of the reported issue.
Rule Reporter Class Methods	The rule reporter instance you create provides methods to handle reported issues.

RulePack Class Methods

The rule pack manager instance provides methods to access rule pack data.

The Oracle JAF rule pack manager provides the following methods that you can call on an instance of a RulePack object that you obtain from the Rule context object.

Method	Description
getPackInfo()	Returns an object that contains a read-only copy of the rule pack summary information. Properties include path, prefix, title, version, enabled, status.
getRuleCustomOptions(string ruleName, string packPrefix)	Returns an object that contains read-only copy of the custom options for a rule. That is, those specified by the user, and not JAF system rule options. Both arguments are optional: if packPrefix is omitted, the current rulepack is assumed. If ruleName is omitted the calling rule's options are returned.
getRuleCustomOption(string property, string ruleName, string packPrefix)	Returns the specified custom option property value for the rule, or null if not found. The ruleName and packPrefix arguments are optional. If packPrefix is omitted, the current rulepack is assumed. If ruleName is omitted the calling rule's option property is returned.
getRuleOptions(string ruleName, string prefix)	Returns an object that contains a read-only copy of the options for a rule. Both arguments are optional: if prefix is omitted, the current rule pack is assumed. If ruleName is omitted the calling rule's options are returned.
getRuleOption(string property, string name, string prefix)	Returns the specified rule option property for the rule. Arguments name and prefix are optional: if prefix is omitted, the current rule pack is assumed. If ruleName is omitted the calling rule's option property is returned.
getPrefix()	Returns a string that is the rule pack prefix.
setRuleOptions(string ruleName, Object options)	Sets the options for the rule in the caller's rule pack. The rulename argument is optional - if omitted, the calling rule's options are updated. options is an object containing the property/values to apply. Returns `true` if the options are successfully applied, else `false`.
isRuleEnabled(string ruleName, string prefix)	Returns `true` if the specified rule is currently enabled. The prefix argument is optional, and if omitted, the rule is assumed to be in the caller's rule pack.
isRuleDisabled(string ruleName, string prefix)	Returns `true` if the specified rule is currently disabled. The prefix is optional, and if omitted, the rule is assumed to be in the caller's rule pack.
disableRule(string ruleName)	Disables the specified rule in the caller's rule pack. Returns `true` if the rule was disabled (or was already disabled) - `false` if the rulename is invalid, or the rule was never registered.
enableRule(string ruleName)	Enables the specified rule in the caller's rule pack. Returns `true` if the rule was enabled (or was already enabled) - `false` if the rulename is invalid, or the rule was never registered. Note: In the current release, only a previously loaded rule (at startup) can be re-enabled. That is, `enableRule()` will not be successful, if the rule was discarded during initialization for any reason, and its `register()` method was thereby never called.
getRuleCount()	Returns the number of rules defined in the calling rule's rule pack.
getEnabledRuleCount()	Returns the number of rules currently enabled in the calling rule's rule pack.
getRuleList()	Returns a list of the rule names in the calling rule's rule pack.
getEnabledRuleList()	Returns an array list of the names of the currently enabled rules in the calling rule's rule pack.
getRule()	Returns the instance of a rule in the caller's rule pack to allow its exported methods to be called.
getExtension()	Returns the rule pack specific data supplied by `setExtension()`.
setExtension(* data)	Sets rule pack specific data that can be retrieved via `getExtension()`. `setExtension()` is typically used in a rule pack's startupRP hook rules. data can be any data type, and can be used to refer to any data, libraries, and son on that is useful to the rule.
sendMsg(string ruleName, ...data)	Sends a data message to the `onMsg()` method of a specific rule in the same pack as the caller. data represents any number of arguments - these arguments are presented to `onMsg()` as an array : onMsg(Object sender, *[] data); where sender is an object of the following format: `{ sender : <string>, // the sending ruleName regType : <string> // the register() type of the calling rule }` Returns the value returned by `onMsg()`. Note that a rule cannot send a data message to itself (to mitigate race conditions).
broadcastMsg(string[] ruleNames, ...data)	Send a data message to the `onMsg()` method of a list of rules in the same pack as the caller. If ruleNames is null, the data is broadcast to all currently enabled rules with an exported `onMsg()` method. Returns the number of rules whose `onMsg()` was invoked. Refer to `sendMsg()` for the format of data.
getInfo()	Returns miscellaneous information about the JAF instance as an object that has the following properties as strings. version: the version formatted as "major:minor:patch" description: a description of the JAF instance packageVer: the JET code base that JAF was built on, formatted as "major:minor:patch" platform: the platform the JAF instance was invoked on

Rule Issue Class Methods

You can create an Issue object and use the provided methods of the Oracle JAF Issue class to set properties of the reported issue.

The Oracle JAF Issue class provides the following constructor and setter methods that you can use to set the properties of the Issue object that you create within the registered event listener function of your audit rule.

The typical usage of the Issue class is to call the constructor method to create an Issue instance with details like the issue description and optional message ID:

var myIssue = new context.Issue(msg [, messageID]);

The severity for the rule is obtained from the rule definition, but this may be overridden within a rule using Issue.setSeverity().

Method	Description
constructor(string msg [, string id])	msg—(optional) a string that is the issue description. id—(optional) a string that is an optional message ID. This will appear in the audit output as `ppp-nnnn`, where `ppp` is the rule pack prefix and `nnnn` is the message ID.
setId(string id)	Sets the id portion of a message id. id—a string that is the trailing ID in a message number. For example, if the id is `1234` and the rule's prefix is `ABC`, then the message number will appear as `ABC-1234`.
setPosition(number line, number column, number startIndex, number endIndex) or setPosition(Object pos)	Overrides the line/column numbers in the audited file that appear in the reported message or JSON. line—the line number in the audited data. column—the column number in the audited data. startIndex—(optional) the starting position in the audited data. endIndex—(optional) the ending position in the audited data. Note that line/column may be specified as null, in which case the line and column will be computed by JAF from startIndex. May also be specified as an object, for example: `issue.setPosition(pos);` where pos is an object with the following format: line—the line number. column—the column number. startIndex or start—the start index. endIndex or end—the end index. The pos object may either be constructed by a rule or can be the return value from `DomUtils.getAttribPosition()`, `DomUtils.getAttribValuePosition()`, or `CssUtils.getPosition()`.
setSeverity(string severity)	Sets the severity of the issue (overriding the rule severity defined in the `rules.json` file, or the modified severity in configuration property ruleMods. May be info, minor, major, critical, or blocker.
setMsgKey(string id)	Sets the message ID for the issue. This overrides the message key obtained from the rule pack's `msgid.json` file if it exists.
setReportedFilePath(string filepath)	Sets the specified file path as the reported file path for the issue. This is designed for use where an issue is being reported by a rulepack lifecycle listener (e.g., `closedownRP`) for a file that was audited earlier. Since no file is actually audited when the issue is created, the issue cannot automatically report a file path. This method permits the rulepack to associate a specific file path to the issue for reporting purposes. Note: This is not required for normal audit cycle rules.

Rule Reporter Class Methods

You can create an Reporter object and use the provided methods of the Oracle JAF Reporter class to handle reported issues.

The Oracle JAF Reporter class provides the following methods that you can use to handle reporting of the Issue object that you pass to the Reporter instance in the registered event listener function of your audit rule.

The typical usage of a Reporter instance is to call the addIssue() method:

context.reporter.addIssue(myIssue, context);

Method	Description
addIssue(Object issue, Object context [, string severity])	Adds an `Issue` object to be reported. issue—an `Issue` object created via `new context.Issue(...)` . context—the context object passed to the rule. severity—(optional) allows a rule to override the rule severity. May be infor, minor, major, critical, or blocker.
clearIssues()	Removes all issues added to the `Reporter` instance for the current file.
getCount()	Returns the current number of issues added to the `Reporter` instance for the current file.
getFormat()	Returns the current output format: `prose` or `json`.