Package ghidra.app.util.headless

# Class HeadlessOptions

java.lang.Object
ghidra.app.util.headless.HeadlessOptions

public class HeadlessOptions extends 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)` or `HeadlessAnalyzer.processURL(java.net.URL, List)` are performed, these options should be reset and adjusted as necessary.

- ## Method Summary

  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`
  `enableRecursiveProcessing(boolean enabled, Integer depth)`
  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(String userID, String keystorePath, boolean allowPasswordPrompt)`
  Set Ghidra Server client credentials to be used with "shared" projects.
  `void`
  `setCommitFiles(boolean commit, 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(String languageId, String compilerSpecId)`
  Sets the language and compiler spec from the provided input.
  `void`
  `setLoader(String loaderName, List<Pair<String,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(String stringInSecs)`
  Set analyzer timeout on a per-file basis.
  `void`
  `setPostScripts(List<String> postScripts)`
  Set the ordered list of scripts to execute immediately following import and and analysis of a program.
  `void`
  `setPostScriptsWithArgs(List<Pair<String,String[]>> postScripts)`
  Set the ordered list of scripts to execute immediately following import and and analysis of a program.
  `void`
  `setPreScripts(List<String> preScripts)`
  Set the ordered list of scripts to execute immediately following import and prior to analyzing an imported program.
  `void`
  `setPreScriptsWithArgs(List<Pair<String,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(String paths)`
  List of valid .properties file directory paths, separated by a ';'.
  `void`
  `setPropertiesFileDirectories(List<String> newPaths)`
  Sets one or more locations to find .properties files associated with GhidraScripts.
  `void`
  `setPropertiesFileDirectory(String path)`
  Sets a single location for .properties files associated with GhidraScripts.
  `void`
  `setRunScriptsNoImport(boolean runScriptsOnly, String filename)`
  Set to run scripts (and optionally, analysis) without importing a program.
  `void`
  `setScriptDirectories(String paths)`
  List of valid script directory paths separated by a ';'.
  `void`
  `setScriptDirectories(List<String> newPaths)`
  Set the script source directories to be searched for secondary scripts.

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Method Details

  - ### reset

    public void reset()
    Resets the options to its default settings.

  - ### setRunScriptsNoImport

    public void setRunScriptsNoImport(boolean runScriptsOnly, 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:
      `IllegalArgumentException` - if the specified filename is invalid and contains the path separator character '/'.

  - ### setPreScripts

    public void setPreScripts(List<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(List<Pair<String,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(List<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(List<Pair<String,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(List<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(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(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(List<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(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 project folder to process or a directory or supported `GFileSystem` container file to import
    Parameters:
      `enabled` - if true, enables recursive import/processing

  - ### enableRecursiveProcessing

    public void enableRecursiveProcessing(boolean enabled, Integer depth)
    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 project folder to process or a directory or supported `GFileSystem` container file to import
    Parameters:
      `enabled` - if true, enables recursive import/processing
      `depth` - maximum container recursion depth (could be null to use default)

  - ### 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(String languageId, 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(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(String userID, String keystorePath, boolean allowPasswordPrompt) throws 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:
      `IOException` - if an error occurs while opening the specified keystorePath.

  - ### setCommitFiles

    public void setCommitFiles(boolean commit, String comment)
    Enable committing of processed files to the repository which backs the specified project.
    Parameters:
      `commit` - if true imported files will be committed
      `comment` - 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(String loaderName, List<Pair<String,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.