Package crystalpalace.spec

Class LinkSpec

  • public class LinkSpec
extends java.lang.Object
    An object that parses and interprets a Crystal Palace specification file.

    Call Capability.Parse(byte[]) (ala link) or Capability.None(java.lang.String) (ala piclink) to create the capability argument.

    Call Parse(java.lang.String) to create a LinkSpec object.

    Call run(Capability, Map) to apply a specification file to a Capability and other $ARGUMENTS / %variables passed into the environment.

    That's the API. If there's a problem, the API will throw a SpecParseException or a SpecProgramException.

    This class is not thread safe.

    PERFORMANCE NOTE: The first use of this API, running a .spec file with a binary transform (e.g., code mutation, link-time optimization, etc.) will incur a 500ms penalty. This is because the iced library has to load several constants from within our JAR file. Future calls to this API (with or without binary transforms) should resolve quickly (~20ms in my VM environment).

    Author:
    Adversary Fan Fiction Writers Guild

    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected java.lang.String author
      the author of this .spec file (if specified)
      protected java.lang.String description
      a description of the tradecraft/technique in this .spec file
      protected java.lang.String license
      License for the code and rules in this .spec file.
      protected java.lang.String name
      the short name of the technique/tradecraft in this .spec file
      protected java.lang.String parent
      the file associated with this spec.
      protected crystalpalace.spec.SpecProgram program
      the execution environment for applying this specification to passed in variables
      protected java.lang.String reference
      URL for the tradecraft/technique in this .spec file
      protected java.util.Map variables
      meta-information about the variables this .spec accepts

    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      protected LinkSpec​(crystalpalace.spec.SpecParser parser, java.lang.String parent)
      The constructor for our LinkSpec.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void addLogger​(SpecLogger logger)
      register a logger to receive output (e.g., echo command) from Crystal Palace.
      protected void defineVariable​(java.lang.String varname, java.lang.String desc, java.lang.String allowed, java.lang.String defvalue)
      define a variable that this .spec accepts
      java.lang.String getAuthor()
      Return the author of this tradecraft.
      java.lang.String getDescription()
      Return a description of the technique/tradecraft.
      java.lang.String getFile()
      Get the name of the file associated with this .spec.
      java.lang.String getLicense()
      Return the software license associated with the technique/tradecraft.
      java.lang.String getName()
      Return the name of the technique/tradecraft.
      java.lang.String getName​(java.lang.String defaultv)
      Return the name of the technique/tradecraft.
      java.lang.String getReference()
      Return URL or other reference associated with the technique/tradecraft.
      java.lang.String getTargets()
      Return the targets (e.g., x86, x64) of this tradecraft file.
      java.util.List getVariables()
      Return the global variable meta-information associated with this tradecraft file.
      protected void meta​(java.lang.String verb, java.lang.String value)
      set a meta-value for this specification file (e.g., name, reference, describe, etc.)
      static LinkSpec Parse​(java.lang.String parent)
      Parse a .spec file and return a ready-to-run LinkSpec object.
      static LinkSpec Parse​(java.lang.String parent, java.lang.String content)
      Parse a .spec file and return a ready-to-run LinkSpec object.
      protected void populateDefaults​(java.util.Map env)
      Pre-process environment with the help of variable meta-information.
      void removeLogger​(SpecLogger logger)
      remove a registered logger
      byte[] run​(Capability capability, java.util.Map vars)
      Apply this specification file's directives to the passed in parameters.
      LinkResult runAndGenerate​(Capability capability, java.util.Map vars)
      Apply this specification file's directives to the passed in parameters AND generate yara rules.
      java.util.Map runConfig​(Capability capability, java.util.Map vars)
      Apply this specification file's directives to the passed in vars to set variables.
      boolean targets​(java.lang.String arch)
      Check if this specification has this specific target.

      • Methods inherited from class java.lang.Object

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

    • Field Detail

      • parent

        protected java.lang.String parent
        the file associated with this spec.

      • author

        protected java.lang.String author
        the author of this .spec file (if specified)

      • name

        protected java.lang.String name
        the short name of the technique/tradecraft in this .spec file

      • description

        protected java.lang.String description
        a description of the tradecraft/technique in this .spec file

      • reference

        protected java.lang.String reference
        URL for the tradecraft/technique in this .spec file

      • license

        protected java.lang.String license
        License for the code and rules in this .spec file.

      • variables

        protected java.util.Map variables
        meta-information about the variables this .spec accepts

      • program

        protected crystalpalace.spec.SpecProgram program
        the execution environment for applying this specification to passed in variables

    • Method Detail

      • meta

        protected void meta​(java.lang.String verb,
                    java.lang.String value)
        set a meta-value for this specification file (e.g., name, reference, describe, etc.)
        Parameters:
        verb - the meta-command that describes some aspect of our .spec; it's the key we're setting.
        value - the value to set it to

      • defineVariable

        protected void defineVariable​(java.lang.String varname,
                              java.lang.String desc,
                              java.lang.String allowed,
                              java.lang.String defvalue)
        define a variable that this .spec accepts
        Parameters:
        varname - the variable name, must begin with % or $
        desc - the text description of the variable
        allowed - a comma-separated list of allowed values (%var only) OR null
        defvalue - the default value (%vars only) OR null

      • populateDefaults

        protected void populateDefaults​(java.util.Map env)
        Pre-process environment with the help of variable meta-information. This function will populate default values, if needed.

      • addLogger

        public void addLogger​(SpecLogger logger)
        register a logger to receive output (e.g., echo command) from Crystal Palace.
        Parameters:
        logger - the object that receives messages from Crystal Palace.

      • removeLogger

        public void removeLogger​(SpecLogger logger)
        remove a registered logger
        Parameters:
        logger - the object that (should no longer) receive messages from Crystal Palace.

      • getFile

        public java.lang.String getFile()
        Get the name of the file associated with this .spec. The files does not actually have to exist. It's set by the API when Parse(java.lang.String, java.lang.String) is called.
        Returns:
        the file associated with this spec.

      • getAuthor

        public java.lang.String getAuthor()
        Return the author of this tradecraft. This value is set with the author "name" command in the .spec file.
        Returns:
        the author value

      • getTargets

        public java.lang.String getTargets()
        Return the targets (e.g., x86, x64) of this tradecraft file. This value is populated by querying the targets in the .spec file
        Returns:
        a comma-separated list of targets

      • getVariables

        public java.util.List getVariables()
        Return the global variable meta-information associated with this tradecraft file. These values are set by defval "%var", defraw "$VAR", and defenum "%var" in the .spec file
        Returns:
        a java.util.List of java.util.Map objects containing variable meta-info.

      • getName

        public java.lang.String getName()
        Return the name of the technique/tradecraft. This value is set with the name "tradecraft name" command in the .spec file. If a name is not set, this returns a derived name from the .spec file.
        Returns:
        the name value

      • getName

        public java.lang.String getName​(java.lang.String defaultv)
        Return the name of the technique/tradecraft. This value is set with the name "tradecraft name" command in the .spec file. If a name is not set, the defaultv is returned
        Parameters:
        defaultv - the default name value, if there is no name set.
        Returns:
        the name value

      • getDescription

        public java.lang.String getDescription()
        Return a description of the technique/tradecraft. This value is set with the describe "my technique does this" command in the .spec file.
        Returns:
        the description value

      • getLicense

        public java.lang.String getLicense()
        Return the software license associated with the technique/tradecraft. This value is set with the license "bsd" command in the .spec file.
        Returns:
        the reference value

      • getReference

        public java.lang.String getReference()
        Return URL or other reference associated with the technique/tradecraft. This value is set with the reference "https://..." command in the .spec file.
        Returns:
        the reference value

      • targets

        public boolean targets​(java.lang.String arch)
        Check if this specification has this specific target. Valid values include x86, x64.
        Parameters:
        arch - the target architecture to check
        Returns:
        true if the technique has an option to target the specific arch

      • run

        public byte[] run​(Capability capability,
                  java.util.Map vars)
           throws SpecParseException,
                  SpecProgramException
        Apply this specification file's directives to the passed in parameters.
        Parameters:
        capability - an object with our capability's content and the other capability-specific arguments needed for our program.
        vars - is a mapping of $KEY to byte[] and %VAR to "string" values used in the specification file. Each variable name must begin with the right sigil ($, %) to be accessible within the spec environment.
        Returns:
        the position-independent code (usually) generated by applying this specification to the arguments
        Throws:
        SpecParseException - if a specification file called run "file.spec" from this specification has syntax errors.
        SpecProgramException - if an error occurs or is detected during the application of this specification file.

      • runAndGenerate

        public LinkResult runAndGenerate​(Capability capability,
                                 java.util.Map vars)
                          throws SpecParseException,
                                 SpecProgramException
        Apply this specification file's directives to the passed in parameters AND generate yara rules.
        Parameters:
        capability - an object with our capability's content and the other capability-specific arguments needed for our program.
        vars - is a mapping of $KEY to byte[] and %VAR to "string" values used in the specification file. Each variable name must begin with the right sigil ($, %) to be accessible within the spec environment.
        Returns:
        LinkResult object with Yara rules and linker output
        Throws:
        SpecParseException - if a specification file called run "file.spec" from this specification has syntax errors.
        SpecProgramException - if an error occurs or is detected during the application of this specification file.

      • runConfig

        public java.util.Map runConfig​(Capability capability,
                               java.util.Map vars)
                        throws SpecParseException,
                               SpecProgramException
        Apply this specification file's directives to the passed in vars to set variables. The run specification file must end with an empty stack.
        Parameters:
        capability - an object with our capability's content and the other capability-specific arguments needed for our program.
        vars - is a mapping of $KEY to byte[] and %VAR to "string" values used in the specification file. Each variable name must begin with the right sigil ($, %) to be accessible within the spec environment.
        Returns:
        the updated vars object.
        Throws:
        SpecParseException - if a specification file called run "file.spec" from this specification has syntax errors.
        SpecProgramException - if an error occurs or is detected during the application of this specification file.

      • Parse

        public static LinkSpec Parse​(java.lang.String parent,
                             java.lang.String content)
                      throws SpecParseException
        Parse a .spec file and return a ready-to-run LinkSpec object.
        Parameters:
        parent - the parent file of this .spec content. Returned by #getFile.
        content - the .spec file content
        Returns:
        a LinkSpec object.
        Throws:
        SpecParseException - if a syntax error or mis-used command is detected

      • Parse

        public static LinkSpec Parse​(java.lang.String parent)
                      throws SpecParseException,
                             java.io.IOException
        Parse a .spec file and return a ready-to-run LinkSpec object.
        Parameters:
        parent - The name of the .spec file to read and parse.
        Returns:
        a LinkSpec object
        Throws:
        SpecParseException - if a syntax error or mis-used command is detected
        java.io.IOException - if we can't read the .spec file