Package org.zaproxy.zap.control

Class AddOn

  • public class AddOn
extends java.lang.Object

    • Field Detail

      • MANIFEST_FILE_NAME

        public static final java.lang.String MANIFEST_FILE_NAME
        The name of the manifest file, contained in the add-ons.

        The manifest is expected to be in the root of the ZIP file.

        Since:
        2.6.0
        See Also:
        Constant Field Values

      • FILE_EXTENSION

        public static final java.lang.String FILE_EXTENSION
        The file extension of ZAP add-ons.
        Since:
        2.6.0
        See Also:
        Constant Field Values

    • Constructor Detail

      • AddOn

        public AddOn​(java.nio.file.Path file)
      throws java.io.IOException
        Constructs an AddOn from the given file.

        The "ZapAddOn.xml" ZIP file entry is read after validating that the add-on is a valid add-on.

        The installation status of the add-on is 'not installed'.

        Parameters:
        file - the file of the add-on
        Throws:
        AddOn.InvalidAddOnException - (since 2.8.0) if the given file does not exist, does not have a valid add-on file name, or an error occurred while reading the add-on manifest ("ZapAddOn.xml").
        java.io.IOException - if an error occurred while reading/validating the file.
        See Also:
        isAddOn(Path)

      • AddOn

        public AddOn​(java.lang.String id,
             java.io.File baseDir,
             org.apache.commons.configuration.SubnodeConfiguration xmlData)
      throws java.net.MalformedURLException,
             java.io.IOException
        Constructs an AddOn from an add-on entry of ZapVersions.xml file. The installation status of the add-on is 'not installed'.

        The "ZapAddOn.xml" ZIP file entry is read, if the add-on file exists locally.

        Parameters:
        id - the id of the add-on
        baseDir - the base directory where the add-on is located
        xmlData - the source of add-on entry of ZapVersions.xml file
        Throws:
        java.net.MalformedURLException - if the URL of the add-on is malformed
        java.io.IOException - if an error occurs while reading the XML data

    • Method Detail

      • isAddOnFileName

        public static boolean isAddOnFileName​(java.lang.String fileName)
        Tells whether or not the given file name matches the name of a ZAP add-on.

        The file name must have as file extension FILE_EXTENSION.

        Parameters:
        fileName - the name of the file to check
        Returns:
        true if the given file name is the name of an add-on, false otherwise.
        Since:
        2.6.0

      • isAddOn

        public static boolean isAddOn​(java.nio.file.Path file)
        Tells whether or not the given file is a ZAP add-on.

        An add-on is a ZIP file that contains, at least, a "ZapAddOn.xml" file.

        Parameters:
        file - the file to be checked
        Returns:
        true if the given file is an add-on, false otherwise.
        Since:
        2.6.0
        See Also:
        isAddOnFileName(String), isValidAddOn(Path)

      • isValidAddOn

        public static AddOn.ValidationResult isValidAddOn​(java.nio.file.Path file)
        Tells whether or not the given file is a ZAP add-on.
        Parameters:
        file - the file to be checked.
        Returns:
        the result of the validation.
        Since:
        2.8.0
        See Also:
        isAddOn(Path)

      • createAddOn

        public static java.util.Optional<AddOn> createAddOn​(java.nio.file.Path file)
        Convenience method that attempts to create an AddOn from the given file.

        A warning is logged if the add-on is invalid and an error if an error occurred while creating it.

        Parameters:
        file - the file of the add-on.
        Returns:
        a container with the AddOn, or empty if not valid or an error occurred while creating it.
        Since:
        2.8.0

      • getId

        public java.lang.String getId()

      • setId

        public void setId​(java.lang.String id)

      • getName

        public java.lang.String getName()

      • setName

        public void setName​(java.lang.String name)

      • getDescription

        public java.lang.String getDescription()

      • setDescription

        public void setDescription​(java.lang.String description)

      • getFileVersion

        @Deprecated
public int getFileVersion()
        Deprecated.
        (2.7.0) Use getVersion() instead.
        Gets the file version of the add-on.
        Returns:
        the file version.

      • getVersion

        public Version getVersion()
        Gets the semantic version of this add-on.

        Since 2.7.0, for add-ons that use just an integer as the version it's appended ".0.0", for example, for version 14 it returns the version 14.0.0.

        Returns:
        the semantic version of the add-on, since 2.7.0, never null.
        Since:
        2.4.0

      • setStatus

        public void setStatus​(AddOn.Status status)

      • getChanges

        public java.lang.String getChanges()

      • setChanges

        public void setChanges​(java.lang.String changes)

      • getNormalisedFileName

        public java.lang.String getNormalisedFileName()
        Gets the normalised file name of the add-on.

        Should be used when copying the file from an "unknown" source (e.g. manually installed).

        Returns:
        the normalised file name.
        Since:
        2.6.0
        See Also:
        getFile()

      • getFile

        public java.io.File getFile()
        Gets the file of the add-on.
        Returns:
        the file of the add-on.
        See Also:
        getNormalisedFileName()

      • setFile

        public void setFile​(java.io.File file)

      • getUrl

        public java.net.URL getUrl()

      • setUrl

        public void setUrl​(java.net.URL url)

      • getSize

        public long getSize()

      • setSize

        public void setSize​(long size)

      • getAuthor

        public java.lang.String getAuthor()

      • setAuthor

        public void setAuthor​(java.lang.String author)

      • getClassLoader

        public java.lang.ClassLoader getClassLoader()
        Gets the class loader of the add-on.
        Returns:
        the class loader of the add-on, null if the add-on is not installed.
        Since:
        2.8.0

      • setClassLoader

        public void setClassLoader​(java.lang.ClassLoader classLoader)
        Sets the class loader of the add-on.

        Note: This method should be called only by bootstrap classes.

        Parameters:
        classLoader - the class loader of the add-on, might be null.
        Since:
        2.8.0

      • setInstallationStatus

        public void setInstallationStatus​(AddOn.InstallationStatus installationStatus)
        Sets the installation status of the add-on.
        Parameters:
        installationStatus - the new installation status
        Throws:
        java.lang.IllegalArgumentException - if the given installationStatus is null.
        Since:
        2.4.0

      • getInstallationStatus

        public AddOn.InstallationStatus getInstallationStatus()
        Gets installations status of the add-on.
        Returns:
        the installation status, never null
        Since:
        2.4.0

      • hasZapAddOnEntry

        public boolean hasZapAddOnEntry()

      • getAddOnClassnames

        public org.zaproxy.zap.control.AddOnClassnames getAddOnClassnames()
        Gets the classnames that can be loaded for the add-on.
        Returns:
        the classnames that can be loaded
        Since:
        2.4.3

      • getExtensions

        public java.util.List<java.lang.String> getExtensions()

      • getExtensionsWithDeps

        public java.util.List<java.lang.String> getExtensionsWithDeps()
        Returns the classnames of Extensionsthat have dependencies on add-ons.
        Returns:
        the classnames of the extensions with dependencies on add-ons.
        See Also:
        hasExtensionsWithDeps()

      • getExtensionAddOnClassnames

        public org.zaproxy.zap.control.AddOnClassnames getExtensionAddOnClassnames​(java.lang.String classname)
        Returns the classnames that can be loaded for the given Extension (with dependencies).
        Parameters:
        classname - the classname of the extension
        Returns:
        the classnames that can be loaded
        Since:
        2.4.3
        See Also:
        hasExtensionsWithDeps()

      • hasExtensionsWithDeps

        public boolean hasExtensionsWithDeps()
        Tells whether or not this add-on has at least one extension with dependencies.
        Returns:
        true if the add-on has at leas one extension with dependencies, false otherwise
        See Also:
        getExtensionsWithDeps()

      • getLoadedExtensionsWithDeps

        public java.util.List<Extension> getLoadedExtensionsWithDeps()
        Gets the extensions of this add-on that have dependencies and were loaded.
        Returns:
        an unmodifiable List with the extensions of this add-on that have dependencies and were loaded
        Since:
        2.4.0

      • getLoadedExtensions

        public java.util.List<Extension> getLoadedExtensions()
        Gets the extensions of this add-on that were loaded.
        Returns:
        an unmodifiable List with the extensions of this add-on that were loaded
        Since:
        2.4.0

      • addLoadedExtension

        public void addLoadedExtension​(Extension extension)
        Adds the given extension to the list of loaded extensions of this add-on.

        This add-on is set to the given extension.

        Parameters:
        extension - the extension of this add-on that was loaded
        Throws:
        java.lang.IllegalArgumentException - if extension is null
        Since:
        2.4.0
        See Also:
        removeLoadedExtension(Extension), Extension.setAddOn(AddOn)

      • removeLoadedExtension

        public void removeLoadedExtension​(Extension extension)
        Removes the given extension from the list of loaded extensions of this add-on.

        The add-on of the given extension is set to null.

        The call to this method has no effect if the given extension does not belong to this add-on.

        Parameters:
        extension - the loaded extension of this add-on that should be removed
        Throws:
        java.lang.IllegalArgumentException - if extension is null
        Since:
        2.4.0
        See Also:
        addLoadedExtension(Extension), Extension.setAddOn(AddOn)

      • getAscanrules

        public java.util.List<java.lang.String> getAscanrules()

      • getLoadedAscanrules

        public java.util.List<AbstractPlugin> getLoadedAscanrules()
        Gets the active scan rules of this add-on that were loaded.
        Returns:
        an unmodifiable List with the active scan rules of this add-on that were loaded, never null
        Since:
        2.4.3
        See Also:
        setLoadedAscanrules(List)

      • getPscanrules

        public java.util.List<java.lang.String> getPscanrules()

      • getLoadedPscanrules

        public java.util.List<PluginPassiveScanner> getLoadedPscanrules()
        Gets the passive scan rules of this add-on that were loaded.
        Returns:
        an unmodifiable List with the passive scan rules of this add-on that were loaded, never null
        Since:
        2.4.3
        See Also:
        setLoadedPscanrules(List)

      • getFiles

        public java.util.List<java.lang.String> getFiles()

      • isSameAddOn

        public boolean isSameAddOn​(AddOn addOn)

      • isUpdateTo

        public boolean isUpdateTo​(AddOn addOn)
                   throws java.lang.IllegalArgumentException
        Throws:
        java.lang.IllegalArgumentException

      • canLoadInCurrentVersion

        public boolean canLoadInCurrentVersion()
        Tells whether or not this add-on can be loaded in the currently running ZAP version, as given by Constant.PROGRAM_VERSION.
        Returns:
        true if the add-on can be loaded in the currently running ZAP version, false otherwise
        See Also:
        canLoadInVersion(String), Constant.PROGRAM_VERSION

      • canRunInCurrentJavaVersion

        public boolean canRunInCurrentJavaVersion()
        Tells whether or not this add-on can be run in the currently running Java version.

        This is a convenience method that calls canRunInJavaVersion(String) with the running Java version (as given by SystemUtils.JAVA_VERSION) as parameter.

        Returns:
        true if the add-on can be run in the currently running Java version, false otherwise
        Since:
        2.4.0
        See Also:
        canRunInJavaVersion(String), SystemUtils.JAVA_VERSION

      • canRunInJavaVersion

        public boolean canRunInJavaVersion​(java.lang.String javaVersion)
        Tells whether or not this add-on can be run in the given javaVersion.

        If the given javaVersion is null and this add-on depends on a specific java version the method returns false.

        Parameters:
        javaVersion - the java version that will be checked
        Returns:
        true if the add-on can be loaded in the given javaVersion, false otherwise
        Since:
        2.4.0

      • calculateRunRequirements

        public AddOn.AddOnRunRequirements calculateRunRequirements​(java.util.Collection<AddOn> availableAddOns)
        Calculates the requirements to run this add-on, in the current ZAP and Java versions and with the given availableAddOns.

        If the add-on depends on other add-ons, those add-ons are also checked if are also runnable.

        Note: All the given availableAddOns are expected to be loadable in the currently running ZAP version, that is, the method AddOn.canLoadInCurrentVersion(), returns true.

        Parameters:
        availableAddOns - the other add-ons available
        Returns:
        a requirements to run the add-on, and if not runnable the reason why it's not.
        Since:
        2.4.0
        See Also:
        canLoadInCurrentVersion(), canRunInCurrentJavaVersion(), AddOn.AddOnRunRequirements

      • calculateExtensionRunRequirements

        public AddOn.AddOnRunRequirements calculateExtensionRunRequirements​(Extension extension,
                                                                    java.util.Collection<AddOn> availableAddOns)
        Calculates the requirements to run the given extension, in the current ZAP and Java versions and with the given availableAddOns.

        If the extension depends on other add-ons, those add-ons are checked if are also runnable.

        Note: All the given availableAddOns are expected to be loadable in the currently running ZAP version, that is, the method AddOn.canLoadInCurrentVersion(), returns true.

        Parameters:
        extension - the extension that will be checked
        availableAddOns - the add-ons available
        Returns:
        the requirements to run the extension, and if not runnable the reason why it's not.
        Since:
        2.4.0
        See Also:
        AddOn.AddOnRunRequirements.getExtensionRequirements()

      • calculateExtensionRunRequirements

        public AddOn.AddOnRunRequirements calculateExtensionRunRequirements​(java.lang.String classname,
                                                                    java.util.Collection<AddOn> availableAddOns)
        Calculates the requirements to run the extension with the given classname, in the current ZAP and Java versions and with the given availableAddOns.

        If the extension depends on other add-ons, those add-ons are checked if are also runnable.

        Note: All the given availableAddOns are expected to be loadable in the currently running ZAP version, that is, the method AddOn.canLoadInCurrentVersion(), returns true.

        Parameters:
        classname - the classname of extension that will be checked
        availableAddOns - the add-ons available
        Returns:
        the requirements to run the extension, and if not runnable the reason why it's not.
        Since:
        2.4.0
        See Also:
        AddOn.AddOnRunRequirements.getExtensionRequirements()

      • calculateExtensionInstallRequirements

        public AddOn.AddOnRunRequirements calculateExtensionInstallRequirements​(java.lang.String classname,
                                                                        java.util.Collection<AddOn> availableAddOns)
        Calculates the requirements to install/run the given extension, same as calculateExtensionRunRequirements(String, Collection) but does not require the libraries of the add-ons (this or dependencies) to exist in the file system.
        Parameters:
        classname - the classname of extension that will be checked.
        availableAddOns - the add-ons available.
        Returns:
        the requirements to install/run the extension, and if not runnable the reason why it's not.
        Since:
        2.9.0
        See Also:
        AddOn.AddOnRunRequirements.getExtensionRequirements()

      • dependsOn

        public boolean dependsOn​(Extension extension,
                         AddOn addOn)
        Tells whether or not the given extension has a (direct) dependency on the given addOn (including version).
        Parameters:
        extension - the extension that will be checked
        addOn - the add-on that will be checked in the dependencies on the extension
        Returns:
        true if the extension depends on the given add-on, false otherwise.
        Since:
        2.4.0

      • isExtensionLoaded

        public boolean isExtensionLoaded​(java.lang.String classname)
        Tells whether or not the extension with the given classname is loaded.
        Parameters:
        classname - the classname of the extension
        Returns:
        true if the extension is loaded, false otherwise
        Since:
        2.4.0

      • getMinimumJavaVersion

        public java.lang.String getMinimumJavaVersion()
        Returns the minimum Java version required to run this add-on or an empty String if there's no minimum version.
        Returns:
        the minimum Java version required to run this add-on or an empty String if no minimum version
        Since:
        2.4.0

      • canLoadInVersion

        public boolean canLoadInVersion​(java.lang.String zapVersion)
        Tells whether or not this add-on can be loaded in the given zapVersion.
        Parameters:
        zapVersion - the ZAP version that will be checked
        Returns:
        true if the add-on can be loaded in the given zapVersion, false otherwise

      • setNotBeforeVersion

        public void setNotBeforeVersion​(java.lang.String notBeforeVersion)

      • setNotFromVersion

        public void setNotFromVersion​(java.lang.String notFromVersion)

      • getNotBeforeVersion

        public java.lang.String getNotBeforeVersion()

      • getNotFromVersion

        public java.lang.String getNotFromVersion()

      • getInfo

        public java.net.URL getInfo()

      • setInfo

        public void setInfo​(java.net.URL info)

      • getRepo

        public java.net.URL getRepo()
        Gets the URL to the browsable repo.
        Returns:
        the URL to the repo, might be null.
        Since:
        2.9.0

      • getHash

        public java.lang.String getHash()

      • getReleaseDate

        public java.lang.String getReleaseDate()
        Gets the date when the add-on was released.

        The date has the format YYYY-MM-DD.

        Note: The date is only available for add-ons created from the marketplace.

        Returns:
        the release date, or null if not available.
        Since:
        2.10.0

      • getBundleData

        public AddOn.BundleData getBundleData()
        Gets the data of the bundle declared in the manifest.
        Returns:
        the bundle data, never null.
        Since:
        2.8.0
        See Also:
        getResourceBundle()

      • getResourceBundle

        public java.util.ResourceBundle getResourceBundle()
        Gets the resource bundle of the add-on.
        Returns:
        the resource bundle, or null if none.
        Since:
        2.8.0

      • setResourceBundle

        public void setResourceBundle​(java.util.ResourceBundle resourceBundle)
        Sets the resource bundle of the add-on.

        Note: This method should be called only by bootstrap classes.

        Parameters:
        resourceBundle - the resource bundle of the add-on, might be null.
        Since:
        2.8.0
        See Also:
        getBundleData()

      • getHelpSetData

        public AddOn.HelpSetData getHelpSetData()
        Gets the data for the HelpSet, declared in the manifest.
        Returns:
        the HelpSet data, never null.
        Since:
        2.8.0

      • setMandatory

        public void setMandatory​(boolean mandatory)
        Sets if this add-on is mandatory.

        Note: This method should be called only by bootstrap classes.

        Parameters:
        mandatory - true if the add-on is mandatory, false otherwise.
        Since:
        2.12.0
        See Also:
        isMandatory()

      • isMandatory

        public boolean isMandatory()
        Tells whether or not this add-on is mandatory.
        Returns:
        true if the add-on is mandatory, false otherwise.
        Since:
        2.12.0

      • getIdsAddOnDependencies

        public java.util.List<java.lang.String> getIdsAddOnDependencies()
        Returns the IDs of the add-ons dependencies, an empty collection if none.
        Returns:
        the IDs of the dependencies.
        Since:
        2.4.0

      • dependsOn

        public boolean dependsOn​(AddOn addOn)
        Tells whether or not this add-on has a (direct) dependency on the given addOn (including version).
        Parameters:
        addOn - the add-on that will be checked
        Returns:
        true if it depends on the given add-on, false otherwise.
        Since:
        2.4.0

      • dependsOn

        public boolean dependsOn​(java.util.Collection<AddOn> addOns)
        Tells whether or not this add-on has a (direct) dependency on any of the given addOns (including version).
        Parameters:
        addOns - the add-ons that will be checked
        Returns:
        true if it depends on any of the given add-ons, false otherwise.
        Since:
        2.4.0

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object

      • equals

        public boolean equals​(java.lang.Object obj)
        Two add-ons are considered equal if both add-ons have the same ID and version.
        Overrides:
        equals in class java.lang.Object