Package ghidra.app.util.headless
Class HeadlessOptions
- java.lang.Object
-
- ghidra.app.util.headless.HeadlessOptions
-
public class HeadlessOptions extends java.lang.Object
Options for headless analyzer.Option state may be adjusted to reflect assumed options during processing. If multiple invocations of either
HeadlessAnalyzer.processLocal(String, String, String, List)
orHeadlessAnalyzer.processURL(java.net.URL, List)
are performed, these options should be reset and adjusted as necessary.
-
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description void
enableAnalysis(boolean enabled)
Auto-analysis is enabled by default following import.void
enableOverwriteOnConflict(boolean enabled)
During import, the default behavior is to skip the import if a conflict occurs within the destination folder.void
enableReadOnlyProcessing(boolean enabled)
When readOnly processing is enabled, any changes made by script or analyzers are discarded when the Headless Analyzer exits.void
enableRecursiveProcessing(boolean enabled)
This method can be used to enable recursive processing of files during-import
or-process
modes.void
reset()
Resets the options to its default settings.void
setClientCredentials(java.lang.String userID, java.lang.String keystorePath, boolean allowPasswordPrompt)
Set Ghidra Server client credentials to be used with "shared" projects.void
setCommitFiles(boolean commit, java.lang.String comment)
Enable committing of processed files to the repository which backs the specified project.void
setDeleteCreatedProjectOnClose(boolean enabled)
Set project delete flag which allows temporary projects created to be deleted upon completion.void
setLanguageAndCompiler(java.lang.String languageId, java.lang.String compilerSpecId)
Sets the language and compiler spec from the provided input.void
setLoader(java.lang.String loaderName, java.util.List<Pair<java.lang.String,java.lang.String>> loaderArgs)
Sets the loader to use for imports, as well as any loader-specific arguments.void
setMaxCpu(int cpu)
Sets the maximum number of cpu cores to use during headless processing.void
setOkToDelete(boolean deleteOk)
void
setPerFileAnalysisTimeout(int secs)
void
setPerFileAnalysisTimeout(java.lang.String stringInSecs)
Set analyzer timeout on a per-file basis.void
setPostScripts(java.util.List<java.lang.String> postScripts)
Set the ordered list of scripts to execute immediately following import and and analysis of a program.void
setPostScriptsWithArgs(java.util.List<Pair<java.lang.String,java.lang.String[]>> postScripts)
Set the ordered list of scripts to execute immediately following import and and analysis of a program.void
setPreScripts(java.util.List<java.lang.String> preScripts)
Set the ordered list of scripts to execute immediately following import and prior to analyzing an imported program.void
setPreScriptsWithArgs(java.util.List<Pair<java.lang.String,java.lang.String[]>> preScripts)
Set the ordered list of scripts and their arguments to execute immediately following import and prior to analyzing an imported program.void
setPropertiesFileDirectories(java.lang.String paths)
List of valid .properties file directory paths, separated by a ';'.void
setPropertiesFileDirectories(java.util.List<java.lang.String> newPaths)
Sets one or more locations to find .properties files associated with GhidraScripts.void
setPropertiesFileDirectory(java.lang.String path)
Sets a single location for .properties files associated with GhidraScripts.void
setRunScriptsNoImport(boolean runScriptsOnly, java.lang.String filename)
Set to run scripts (and optionally, analysis) without importing a program.void
setScriptDirectories(java.lang.String paths)
List of valid script directory paths separated by a ';'.void
setScriptDirectories(java.util.List<java.lang.String> newPaths)
Set the script source directories to be searched for secondary scripts.
-
-
-
Method Detail
-
reset
public void reset()
Resets the options to its default settings.
-
setRunScriptsNoImport
public void setRunScriptsNoImport(boolean runScriptsOnly, java.lang.String filename)
Set to run scripts (and optionally, analysis) without importing a program. Scripts will run on specified folder or program that already exists in the project.- Parameters:
runScriptsOnly
- if true, no imports will occur and scripts (and analysis, if enabled) will run on the specified existing program or directory of programs.filename
- name of specific project file or folder to be processed (the location is passed in elsewhere by the user). If null, user has not specified a file to process -- therefore, the entire directory will be processed. The filename should not include folder path elements which should be specified separately via project or URL specification.- Throws:
java.lang.IllegalArgumentException
- if the specified filename is invalid and contains the path separator character '/'.
-
setPreScripts
public void setPreScripts(java.util.List<java.lang.String> preScripts)
Set the ordered list of scripts to execute immediately following import and prior to analyzing an imported program. If import not performed, these scripts will execute once prior to any post-scripts.- Parameters:
preScripts
- list of script names
-
setPreScriptsWithArgs
public void setPreScriptsWithArgs(java.util.List<Pair<java.lang.String,java.lang.String[]>> preScripts)
Set the ordered list of scripts and their arguments to execute immediately following import and prior to analyzing an imported program. If import not performed, these scripts will execute once prior to any post-scripts.- Parameters:
preScripts
- list of script names/script argument pairs
-
setPostScripts
public void setPostScripts(java.util.List<java.lang.String> postScripts)
Set the ordered list of scripts to execute immediately following import and and analysis of a program. If import not performed, these scripts will execute once following any pre-scripts.- Parameters:
postScripts
- list of script names
-
setPostScriptsWithArgs
public void setPostScriptsWithArgs(java.util.List<Pair<java.lang.String,java.lang.String[]>> postScripts)
Set the ordered list of scripts to execute immediately following import and and analysis of a program. If import not performed, these scripts will execute once following any pre-scripts.- Parameters:
postScripts
- list of script names/script argument pairs
-
setScriptDirectories
public void setScriptDirectories(java.util.List<java.lang.String> newPaths)
Set the script source directories to be searched for secondary scripts. The default set of enabled script directories within the Ghidra installation will be appended to the specified list of newPaths. Individual Paths may be constructed relative to Ghidra installation directory, User home directory, or absolute system paths. Examples:Path.GHIDRA_HOME + "/Ghidra/Features/Base/ghidra_scripts" Path.USER_HOME + "/Ghidra/Features/Base/ghidra_scripts" "/shared/ghidra_scripts"
- Parameters:
newPaths
- list of directories to be searched.
-
setScriptDirectories
public void setScriptDirectories(java.lang.String paths)
List of valid script directory paths separated by a ';'. The default set of enabled script directories within the Ghidra installation will be appended to the specified list of newPaths. Individual Paths may be constructed relative to Ghidra installation directory, User home directory, or absolute system paths. Examples:Path.GHIDRA_HOME + "/Ghidra/Features/Base/ghidra_scripts" Path.USER_HOME + "/Ghidra/Features/Base/ghidra_scripts" "/shared/ghidra_scripts"
- Parameters:
paths
- semicolon (';') separated list of directory paths
-
setPropertiesFileDirectory
public void setPropertiesFileDirectory(java.lang.String path)
Sets a single location for .properties files associated with GhidraScripts. Typically, .properties files should be located in the same directory as their corresponding scripts. However, this method may need to be used when circumstances make it impossible to have both files in the same directory (i.e., if the scripts are included in ghidra.jar).- Parameters:
path
- location of .properties file(s)
-
setPropertiesFileDirectories
public void setPropertiesFileDirectories(java.util.List<java.lang.String> newPaths)
Sets one or more locations to find .properties files associated with GhidraScripts. Typically, .properties files should be located in the same directory as their corresponding scripts. However, this method may need to be used when circumstances make it impossible to have both files in the same directory (i.e., if the scripts are included in ghidra.jar).- Parameters:
newPaths
- potential locations of .properties file(s)
-
setPropertiesFileDirectories
public void setPropertiesFileDirectories(java.lang.String paths)
List of valid .properties file directory paths, separated by a ';'. Typically, .properties files should be located in the same directory as their corresponding scripts. However, this method may need to be used when circumstances make it impossible to have both files in the same directory (i.e., if the scripts are included in ghidra.jar).- Parameters:
paths
- String representation of directories (each separated by ';')
-
enableOverwriteOnConflict
public void enableOverwriteOnConflict(boolean enabled)
During import, the default behavior is to skip the import if a conflict occurs within the destination folder. This method can be used to force the original conflicting file to be removed prior to import. If the pre-existing file is versioned, the commit option must also be enabled to have the overwrite remove the versioned file.- Parameters:
enabled
- if true conflicting domain files will be removed from the project prior to importing the new file.
-
enableRecursiveProcessing
public void enableRecursiveProcessing(boolean enabled)
This method can be used to enable recursive processing of files during-import
or-process
modes. In order for recursive processing of files to occur, the user must have specified a directory (and not a specific file) for the Headless Analyzer to import or process.- Parameters:
enabled
- if true, enables recursive processing
-
enableReadOnlyProcessing
public void enableReadOnlyProcessing(boolean enabled)
When readOnly processing is enabled, any changes made by script or analyzers are discarded when the Headless Analyzer exits. When used with import mode, the imported program file will not be saved to the project or repository.- Parameters:
enabled
- if true, enables readOnly processing or import
-
setDeleteCreatedProjectOnClose
public void setDeleteCreatedProjectOnClose(boolean enabled)
Set project delete flag which allows temporary projects created to be deleted upon completion. This option has no effect if a Ghidra URL or an existing project was specified. This option will be assumed when importing with the readOnly option enabled.- Parameters:
enabled
- if true a created project will be deleted when processing is complete.
-
enableAnalysis
public void enableAnalysis(boolean enabled)
Auto-analysis is enabled by default following import. This method can be used to change the enablement of auto-analysis.- Parameters:
enabled
- True if auto-analysis should be enabled; otherwise, false.
-
setLanguageAndCompiler
public void setLanguageAndCompiler(java.lang.String languageId, java.lang.String compilerSpecId) throws InvalidInputException
Sets the language and compiler spec from the provided input. Any null value will attempt a "best-guess" if possible.- Parameters:
languageId
- The language to set.compilerSpecId
- The compiler spec to set.- Throws:
InvalidInputException
- if the language and compiler spec combination is not valid.
-
setPerFileAnalysisTimeout
public void setPerFileAnalysisTimeout(java.lang.String stringInSecs) throws InvalidInputException
Set analyzer timeout on a per-file basis.- Parameters:
stringInSecs
- timeout value in seconds (as a String)- Throws:
InvalidInputException
- if the timeout value was not a valid value
-
setPerFileAnalysisTimeout
public void setPerFileAnalysisTimeout(int secs)
-
setClientCredentials
public void setClientCredentials(java.lang.String userID, java.lang.String keystorePath, boolean allowPasswordPrompt) throws java.io.IOException
Set Ghidra Server client credentials to be used with "shared" projects.- Parameters:
userID
- optional userId to use if server permits the user to use a userId which differs from the process owner name.keystorePath
- file path to keystore file containing users private key to be used with PKI or SSH based authentication.allowPasswordPrompt
- if true the user may be prompted for passwords via the console (stdin). Please note that the Java console will echo the password entry to the terminal which may be undesirable.- Throws:
java.io.IOException
- if an error occurs while opening the specified keystorePath.
-
setCommitFiles
public void setCommitFiles(boolean commit, java.lang.String comment)
Enable committing of processed files to the repository which backs the specified project.- Parameters:
commit
- if true imported files will be committedcomment
- optional comment to use when committing
-
setOkToDelete
public void setOkToDelete(boolean deleteOk)
-
setMaxCpu
public void setMaxCpu(int cpu)
Sets the maximum number of cpu cores to use during headless processing.- Parameters:
cpu
- The maximum number of cpu cores to use during headless processing. Setting it to 0 or a negative integer is equivalent to setting it to 1.
-
setLoader
public void setLoader(java.lang.String loaderName, java.util.List<Pair<java.lang.String,java.lang.String>> loaderArgs) throws InvalidInputException
Sets the loader to use for imports, as well as any loader-specific arguments. A null loader will attempt "best-guess" if possible. Loader arguments are not supported if a "best-guess" is made.- Parameters:
loaderName
- The name (simple class name) of the loader to use.loaderArgs
- A list of loader-specific arguments. Could be null if there are none.- Throws:
InvalidInputException
- if an invalid loader name was specified, or if loader arguments were specified but a loader was not.
-
-