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 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.