info.sswap.ontologies.exec.api
Interface Exec
- All Known Implementing Classes:
- ExecImpl, ExecServlet
public interface Exec
Execution of legacy programs. The Exec package allows one to wrap a
non-semantic legacy program and run it as a semantic web service. The package
requires no source code for implementation: simply define the appropriate
RDGPath
(and optional hotboxPath
) in web.xml (see ExecServlet
). Then
place RDF/XML RDG
s in the RDGPath
or place their
JSON equivalents in the hotboxPath
. RDG
data types
should use the data ontology (http://sswapmeet.sswap.info/data)
either explicitly, or usually implicitly, for example as is achieved by using
the mime
ontology at http://sswapmeet.sswap.info/mime.
Invocation of legacy services is then handled automatically by the Exec
package.
WARNING: Security Risk
Running programs that may not have been originally designed for web
invocation has inherent security risks. Many of these risks are not specific
to SSWAP, but are generally applicable; for example, such risks also exist
for traditional CGI (Common Gateway Interface) wrapping.
Risks include:
- Programs such as the UNIX command 'ls' or the Windows' command 'dir'.
These programs, by design, will report server configurations, such as
directory structures outside of the web server container. These types of
programs should never be exposed as web services.
- Programs such as the UNIX 'awk'. Some programs allow users to invoke a
shell, which can enable broad-scale server access based on user input. These
types of programs should never be exposed as web services.
- Programs such as the UNIX 'sed'. Some programs may not explicitly support
shells, but may allow scripted file name reading, writing, deletion, etc.
These types of programs should never be exposed as web services.
- Programs such as the UNIX 'head'. Some programs accept file names as
arguments. This can expose well-known system files, such as /etc/passwd. Even
if file name arguments do not map to existent files, error messages from such
programs can allow probing of a system. These types of programs should never
be exposed as web services.
- Programs that are not "hardened", such as those that execute unsanitized
user input, or contain exploitable bugs. It can be difficult to know if
programs are adequately hardened; best practice is to not expose programs as
web services until they have passed thorough testing.
- Any program. Ultimately, exposing any program as a web service has
inherent risks. Protect against this by running the web server itself with
the minimum permissions and access control rights necessary for it to perform
its job, and exposing programs that are field-proven to provide
well-understood functionality.
The Exec package security model
- The servlet must have a servlet mapping in web.xml. If there is no
mapping, the servlet will not load. If you have no need for the Exec package
this is the safest setting.
- The servlet is mapped in web.xml, but the "RDGPath" parameter is
undefined. The servlet will throw an exception and not load.
- The servlet is mapped and configured, but there are no RDGs in the
RDGPath. Only RDGs in the RDGPath directory are executable.
- If the "hotboxPath" parameter is configured, then the hotbox directory
will be polled for JSON RDG files. If the JSON file is newer than its
equivalent RDF/XML RDG in the RDGPath directory, then it will be sent to the
HTTP API /makeRDG converter, and upon success, an RDG will be placed in the
RDGPath directory. This allows one to simply drop-n-go JSON RDG files and
they will be automatically generated into RDGs and enabled as services.
Hotbox polling will not occur if the hotboxPath is not defined at server
startup. At present, hotbox polling enforces a file name filter (only files
ending in ".json"); sub-directories are not scanned.
- The program to be executed is configured as the value of the
exec:command
property in the service's RDG. The
exec:command
property in a RIG (received from a user invoking
the service) is always ignored (never used); it is replaced by the RDG's
exec:command
.
- The user passes the program's arguments as the value of the
exec:args
property in the RIG. This string is parsed into a
parameter array. Malicious values and weak programs are a security risk here,
since user input will be passed to the program.
- Both the replaced RDG command and the parsed user
exec:args
parameters are passed to the getCommandLine
method. There is no
universal, operating system independent algorithm to parse command line
parameters in all cases. Thus, this method may be overridden to provide
sanitized argument restructuring. This includes redefining the command
itself; e.g., an RDG may define the command as
exec:command = myProgram
, which may be changed to
/usr/local/bin/myProgramVersion2
or anything the provider so
chooses. This allows RDGs to publish generic command names without committing
nor revealing invocation internals.
- The execution environment is set in the
setEnvironment
method. This method may be overridden to set the execution environment as
appropriate. By default, the environment is cleared of all settings.
- The program is executed by passing the command and its arguments directly
to a process execution method. A shell is not explicitly invoked, so there is
no explicit file name expansion or other shell pre-execution interpretation
of the arguments.
- Author:
- Damian Gessler
- See Also:
ExecServlet
Method Summary |
java.lang.String[] |
getCommandLine(java.lang.String commandLineStr)
Basic parsing and sanity checking of the command line. |
void |
setEnvironment(java.util.Map<java.lang.String,java.lang.String> env)
Set the process' execution environment. |
getCommandLine
java.lang.String[] getCommandLine(java.lang.String commandLineStr)
throws TooManyArgumentsException,
ArgumentTooLongException
- Basic parsing and sanity checking of the command line. Parsing implies
deconstructing a single string into a string array analogous to the array
argument passed to Java main(). Override this method to validate, sanitize, and otherwise change the
command and the user arguments.
- Parameters:
commandLineStr
- a concatenation of the RDG
's
exec:command
and the RIG
's
exec:args
.
- Returns:
- Java main() equivalent of command line arguments. The command
itself must be the first element.
- Throws:
ArgumentTooLongException
- if an argument exceeds a preset maximum
TooManyArgumentsException
- if the number of arguments exceeds a preset maximum
setEnvironment
void setEnvironment(java.util.Map<java.lang.String,java.lang.String> env)
- Set the process' execution environment. Override this method to set the
execution environment. Default implementation is to clear the
environment.
- Parameters:
env
- the default environment ProcessBuilder
environment- See Also:
ProcessBuilder.environment()
Copyright (c) 2011, iPlant Collaborative, University of Arizona, Cold Spring Harbor Laboratories, University of Texas at Austin.