Class HeadlessScript
- java.lang.Object
-
- ghidra.program.flatapi.FlatProgramAPI
-
- ghidra.app.script.GhidraScript
-
- ghidra.app.util.headless.HeadlessScript
-
public abstract class HeadlessScript extends GhidraScript
This class is analogous to GhidraScript, except that is only meant to be used with the HeadlessAnalyzer. That is, if a user writes a script that extends HeadlessScript, it should only be run in the Headless environment.
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static classHeadlessScript.HeadlessContinuationOptionOptions for controlling disposition of program after the current script completes.-
Nested classes/interfaces inherited from class ghidra.app.script.GhidraScript
GhidraScript.AnalysisMode
-
-
Field Summary
-
Fields inherited from class ghidra.app.script.GhidraScript
currentAddress, currentHighlight, currentLocation, currentSelection, potentialPropertiesFileLocs, propertiesFileParams, sourceFile, state, writer
-
Fields inherited from class ghidra.program.flatapi.FlatProgramAPI
currentProgram, MAX_REFERENCES_TO, monitor
-
-
Constructor Summary
Constructors Constructor Description HeadlessScript()
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description booleananalysisTimeoutOccurred()Returns whether analysis for the current program has timed out.voidcleanup(boolean success)A callback for scripts to perform any needed cleanup after the script is finishedvoidenableHeadlessAnalysis(boolean b)Enables or disables analysis according to the passed-in boolean value.HeadlessScript.HeadlessContinuationOptiongetHeadlessContinuationOption()Returns the continuation option for the current script (if one has not been set in this script, the option defaults to CONTINUE).java.lang.ObjectgetStoredHeadlessValue(java.lang.String key)Get stored value by key from the HeadlessAnalyzer instance.booleanheadlessStorageContainsKey(java.lang.String key)Returns whether the specified key was stored in the HeadlessAnalyzer instance.booleanisHeadlessAnalysisEnabled()Returns whether analysis is currently enabled or disabled in the HeadlessAnalyzer.booleanisImporting()Returns whether the headless analyzer is currently set to -import mode or not (if not, it is in -process mode).voidrunScript(java.lang.String scriptName, java.lang.String[] scriptArguments, GhidraState scriptState)Runs a script by name with the given arguments using the given state.voidsetHeadlessContinuationOption(HeadlessScript.HeadlessContinuationOption option)Sets the continuation option for this scriptvoidsetHeadlessImportDirectory(java.lang.String importDir)Changes the path in the Ghidra project where imported files are saved.voidstoreHeadlessValue(java.lang.String key, java.lang.Object value)Stores a key/value pair in the HeadlessAnalyzer instance for later use.-
Methods inherited from class ghidra.app.script.GhidraScript
analyzeAll, analyzeChanges, askAddress, askBytes, askChoice, askChoices, askChoices, askDirectory, askDomainFile, askDouble, askFile, askInt, askLanguage, askLong, askProgram, askProjectFolder, askString, askString, askYesNo, clearBackgroundColor, clearBackgroundColor, closeProgram, createHighlight, createProgram, createProgram, createProgram, createSelection, createTableChooserDialog, createTableChooserDialog, execute, getAnalysisOptionDefaultValue, getAnalysisOptionDefaultValues, getAnalysisOptionDescription, getAnalysisOptionDescriptions, getCategory, getCodeUnitFormat, getCurrentAnalysisOptionsAndValues, getDefaultLanguage, getDemangled, getEOLCommentAsRendered, getGhidraVersion, getLanguage, getPlateCommentAsRendered, getPostCommentAsRendered, getPreCommentAsRendered, getProjectRootFolder, getScriptAnalysisMode, getScriptArgs, getScriptName, getSourceFile, getState, getUserName, goTo, goTo, goTo, importFile, importFileAsBinary, isAnalysisOptionDefaultValue, isRunningHeadless, loadPropertiesFile, loadVariablesFromState, openProgram, parseAddress, parseBoolean, parseBytes, parseChoice, parseChoices, parseChoices, parseDirectory, parseDomainFile, parseDouble, parseFile, parseInt, parseLanguageCompileSpecPair, parseLong, parseProjectFolder, popup, print, printerr, printf, println, println, promptToKeepChangesOnException, removeHighlight, removeSelection, resetAllAnalysisOptions, resetAnalysisOption, resetAnalysisOptions, run, runCommand, runCommand, runScript, runScript, runScript, runScriptPreserveMyState, set, setAnalysisOption, setAnalysisOptions, setAnonymousServerCredentials, setBackgroundColor, setBackgroundColor, setCurrentHighlight, setCurrentLocation, setCurrentSelection, setPotentialPropertiesFileLocations, setPropertiesFile, setPropertiesFileLocation, setScriptArgs, setServerCredentials, setSourceFile, setToolStatusMessage, show, show, toHexString, toHexString, toHexString, toHexString, toString, updateStateFromVariables
-
Methods inherited from class ghidra.program.flatapi.FlatProgramAPI
addEntryPoint, addInstructionXref, analyze, clearListing, clearListing, clearListing, clearListing, createAddressSet, createAsciiString, createAsciiString, createBookmark, createByte, createChar, createData, createDouble, createDWord, createDwords, createEquate, createEquate, createExternalReference, createExternalReference, createExternalReference, createFloat, createFragment, createFragment, createFragment, createFragment, createFunction, createLabel, createLabel, createMemoryBlock, createMemoryBlock, createMemoryReference, createMemoryReference, createQWord, createStackReference, createSymbol, createSymbol, createUnicodeString, createWord, disassemble, end, find, find, find, findBytes, findBytes, findBytes, findBytes, findBytes, findPascalStrings, findStrings, getAddressFactory, getBookmarks, getByte, getBytes, getCurrentProgram, getDataAfter, getDataAfter, getDataAt, getDataBefore, getDataBefore, getDataContaining, getDataTypes, getDouble, getEOLComment, getEquate, getEquate, getEquate, getEquates, getFirstData, getFirstFunction, getFirstInstruction, getFirstInstruction, getFloat, getFragment, getFunction, getFunctionAfter, getFunctionAfter, getFunctionAt, getFunctionBefore, getFunctionBefore, getFunctionContaining, getGlobalFunctions, getInstructionAfter, getInstructionAfter, getInstructionAt, getInstructionBefore, getInstructionBefore, getInstructionContaining, getInt, getLastData, getLastFunction, getLastInstruction, getLong, getMemoryBlock, getMemoryBlock, getMemoryBlocks, getMonitor, getNamespace, getPlateComment, getPostComment, getPreComment, getProgramFile, getReference, getReference, getReferencesFrom, getReferencesTo, getShort, getSymbol, getSymbolAfter, getSymbolAfter, getSymbolAt, getSymbolAt, getSymbolAt, getSymbolBefore, getSymbolBefore, getSymbols, getUndefinedDataAfter, getUndefinedDataAt, getUndefinedDataBefore, openDataTypeArchive, removeBookmark, removeData, removeDataAt, removeEntryPoint, removeEquate, removeEquate, removeEquate, removeEquates, removeFunction, removeFunctionAt, removeInstruction, removeInstructionAt, removeMemoryBlock, removeReference, removeSymbol, saveProgram, saveProgram, set, setByte, setBytes, setDouble, setEOLComment, setFloat, setInt, setLong, setPlateComment, setPostComment, setPreComment, setReferencePrimary, setReferencePrimary, setShort, start, toAddr, toAddr, toAddr
-
-
-
-
Method Detail
-
storeHeadlessValue
public void storeHeadlessValue(java.lang.String key, java.lang.Object value) throws ImproperUseExceptionStores a key/value pair in the HeadlessAnalyzer instance for later use.This method, along with the 'getStoredHeadlessValue' method, is useful for debugging and testing the Headless Analyzer (when the user has directly instantiated the HeadlessAnalyzer instead of running it from analyzeHeadless.sh or analyzeHeadless.bat). This method is intended to allow a HeadlessScript to store variables that reflect the current state of processing (at the time the script is being run). Storing variables in the HeadlessAnalyzer instance may be the only way to access the state of processing during cases when the user is forced to run in -readOnly mode, or if there is a value that is only accessible at the scripts stage.
- Parameters:
key- storage key in String formvalue- value to store- Throws:
ImproperUseException- if not in headless mode or headless instance not set- See Also:
getStoredHeadlessValue(String),headlessStorageContainsKey(String)
-
getStoredHeadlessValue
public java.lang.Object getStoredHeadlessValue(java.lang.String key) throws ImproperUseExceptionGet stored value by key from the HeadlessAnalyzer instance.This method, along with the 'storedHeadlessValue' method, is useful for debugging and testing the Headless Analyzer (when the user has directly instantiated the HeadlessAnalyzer instead of running it from analyzeHeadless.sh or analyzeHeadless.bat). This method is intended to allow a HeadlessScript to store variables that reflect the current state of processing (at the time the script is being run). Storing variables in the HeadlessAnalyzer instance may be the only way to access the state of processing during cases when the user is forced to run in -readOnly mode, or if there is a value that is only accessible at the scripts stage.
- Parameters:
key- key to retrieve the desired stored value- Returns:
- stored Object, or null if none exists for that key
- Throws:
ImproperUseException- if not in headless mode or headless instance not set- See Also:
storeHeadlessValue(String, Object),headlessStorageContainsKey(String)
-
headlessStorageContainsKey
public boolean headlessStorageContainsKey(java.lang.String key) throws ImproperUseExceptionReturns whether the specified key was stored in the HeadlessAnalyzer instance.- Parameters:
key- value of key to check for in Headless Analyzer instance- Returns:
- true if the specified key exists
- Throws:
ImproperUseException- if not in headless mode or headless instance not set- See Also:
storeHeadlessValue(String, Object),getStoredHeadlessValue(String)
-
setHeadlessContinuationOption
public void setHeadlessContinuationOption(HeadlessScript.HeadlessContinuationOption option)
Sets the continuation option for this scriptThe continuation option specifies whether to continue or abort follow-on processing, and whether to delete or keep the current program.
- Parameters:
option- HeadlessContinuationOption set by this script- See Also:
getHeadlessContinuationOption()
-
getHeadlessContinuationOption
public HeadlessScript.HeadlessContinuationOption getHeadlessContinuationOption()
Returns the continuation option for the current script (if one has not been set in this script, the option defaults to CONTINUE).The continuation option specifies whether to continue or abort follow-on processing, and whether to delete or keep the current program.
- Returns:
- the current HeadlessContinuationOption
- See Also:
setHeadlessContinuationOption(HeadlessContinuationOption)
-
enableHeadlessAnalysis
public void enableHeadlessAnalysis(boolean b) throws ImproperUseExceptionEnables or disables analysis according to the passed-in boolean value.A script that calls this method should run as a 'preScript', since preScripts execute before analysis would typically run. Running the script as a 'postScript' is ineffective, since the stage at which analysis would have happened has already passed.
This change will persist throughout the current HeadlessAnalyzer session, unless changed again (in other words, once analysis is enabled via script for one program, it will also be enabled for future programs in the current session, unless changed).
- Parameters:
b- true to enable analysis, false to disable analysis- Throws:
ImproperUseException- if not in headless mode or headless instance not set- See Also:
isHeadlessAnalysisEnabled()
-
isHeadlessAnalysisEnabled
public boolean isHeadlessAnalysisEnabled() throws ImproperUseExceptionReturns whether analysis is currently enabled or disabled in the HeadlessAnalyzer.- Returns:
- whether analysis has been enabled or not
- Throws:
ImproperUseException- if not in headless mode or headless instance not set- See Also:
enableHeadlessAnalysis(boolean)
-
isImporting
public boolean isImporting() throws ImproperUseExceptionReturns whether the headless analyzer is currently set to -import mode or not (if not, it is in -process mode). The use of -import mode implies that binaries are actively being imported into the project (with optional scripts/analysis). The use of -process mode implies that existing project files are being processed (using scripts and/or analysis).- Returns:
- whether we are in -import mode or not
- Throws:
ImproperUseException- if not in headless mode or headless instance not set
-
setHeadlessImportDirectory
public void setHeadlessImportDirectory(java.lang.String importDir) throws ImproperUseException, java.io.IOException, InvalidNameExceptionChanges the path in the Ghidra project where imported files are saved. The passed-in path is assumed to be relative to the project root. For example, if the directory structure for the Ghidra project looks like this:MyGhidraProject: /dir1 /innerDir1 /innerDir2Then the following usage would ensure that any files imported after this call would be saved in the MyGhidraProject:/dir1/innerDir2 folder.setHeadlessImportDirectory("dir1/innerDir2");In contrast, the following usages would add new folders to the Ghidra project and save the imported files into the newly-created path:setHeadlessImportDirectory("innerDir2/my/folder");changes the directory structure to:MyGhidraProject: /dir1 /innerDir1 /innerDir2 /my /folderand:setHeadlessImportDirectory("newDir/saveHere");changes the directory structure to:MyGhidraProject: /dir1 /innerDir1 /innerDir2 /newDir /saveHereAs in the examples above, if the desired folder does not already exist, it is created.A change in the import save folder will persist throughout the current HeadlessAnalyzer session, unless changed again (in other words, once the import directory has been changed, it will remain the 'save' directory for import files in the current session, unless changed).
To revert back to the default import location (that which was specified via command line), pass the null object as the argument to this method, as below:
setHeadlessImportDirectory(null); // Sets import save directory to defaultIf a file with the same name already exists in the desired location, it will only be overwritten if "-overwrite" is true.This method is only applicable when using the HeadlessAnalyzer -import mode and is ineffective in -process mode.
- Parameters:
importDir- the absolute path (relative to root) where inputs will be saved- Throws:
ImproperUseException- if not in headless mode or headless instance not setjava.io.IOException- if there are issues creating the folderInvalidNameException- if folder name is invalid
-
analysisTimeoutOccurred
public boolean analysisTimeoutOccurred() throws ImproperUseExceptionReturns whether analysis for the current program has timed out.Analysis will time out only in the case where:
- the users has set an analysis timeout period using the -analysisTimeoutPerFile parameter
- analysis is enabled and has completed
- the current script is being run as a postScript (since postScripts run after analysis)
- Returns:
- whether analysis timeout occurred
- Throws:
ImproperUseException- if not in headless mode or headless instance not set
-
runScript
public void runScript(java.lang.String scriptName, java.lang.String[] scriptArguments, GhidraState scriptState) throws java.lang.ExceptionDescription copied from class:GhidraScriptRuns a script by name with the given arguments using the given state.It attempts to locate the script in the directories defined in
GhidraScriptUtil.getScriptDirectories().The script being run uses the given
GhidraState(e.g., script variables) Any changes to the state by the script being run will be reflected in the given state object. If the given object is the current state, the this scripts state may be changed by the called script.- Overrides:
runScriptin classGhidraScript- Parameters:
scriptName- the name of the script to runscriptArguments- the arguments to pass to the scriptscriptState- the Ghidra state- Throws:
java.lang.IllegalArgumentException- if the script does not existjava.lang.Exception- if any exceptions occur while running the script- See Also:
GhidraScript.runScriptPreserveMyState(String),GhidraScript.runScript(String)
-
cleanup
public void cleanup(boolean success)
Description copied from class:GhidraScriptA callback for scripts to perform any needed cleanup after the script is finished- Overrides:
cleanupin classGhidraScript- Parameters:
success- true if the script was successful
-
-