Package ghidra.app.util.headless

Class HeadlessOptions

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

      • Methods inherited from class java.lang.Object

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

    • 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 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​(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.