Package crystalpalace.spec

Class LinkSpec

java.lang.Object

crystalpalace.spec.LinkSpec

public class LinkSpec
extends java.lang.Object

An object that parses and interprets a Crystal Palace specification file.

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

Call run(byte[], java.util.Map) to apply a specification file to a DLL and other $ARGUMENTS 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.

Author:

Raphael Mudge

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

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method	Description
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	getName()	Return the name of the technique/tradecraft.
static void	main(java.lang.String[] args)	The entrypoint to Crystal Palace.
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.
byte[]	run(byte[] dll_arg, java.util.Map vars)	Apply this specification file's directives to the passed in parameters.
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

program

protected crystalpalace.spec.SpecProgram program

the execution environment for applying this specification to passed in variables

Constructor Detail

LinkSpec

protected LinkSpec(crystalpalace.spec.SpecParser parser,
                   java.lang.String parent)

The constructor for our LinkSpec. Call Parse(java.lang.String, java.lang.String) to create an instance of this class.

Parameters:

parser - the .spec file parser created by Parse(java.lang.String, java.lang.String)

parent - the parent file for this .spec file, returned by getFile()

Method Detail

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

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.

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

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(byte[] dll_arg,
                  java.util.Map vars)
           throws SpecParseException,
                  SpecProgramException

Apply this specification file's directives to the passed in parameters.

Parameters:

dll_arg - our Win32 DLL argument, installed into the environment as $DLL. This value is lightly checked for validity (e.g., MZ/PE headers exist). The architecture of this DLL determines which target to call from the specification file.

vars - a mapping of $KEY to byte[] values made available during the application of the specification file. Each key should begin with '$' 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.

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

main

public static void main(java.lang.String[] args)

The entrypoint to Crystal Palace. This is our main function, does the stuff you know and love.

Parameters:

args - the command-line arguments