Strategic Security Intelligence
Fred Cohen
&Associates
Simulator

Simulator Manual

The simulator is comprised of a set of lisp programs combines with a perl script and web pages that act to form a user friendly simulation environment. For simple web-based use of the simulators as presented, the access points described on the overview page suffice. This manual is for the technically minded user who wants to program their own simulations using the simulation engines and their built-in capabilities.

How the built-in mechanisms work

It may be instructive to start by looking at what the built-in simulation mechanisms do. The following lines are extracted from the SimWeb.pl program that is used to run the simulators from the CD. I have slightly rewritten the code here for readability.

The perl program takes inputs in the form of URLs and manipulates them to form inputs to lisp programs. As you can see, both the "Rooms" game and the "Hack" game operate from the same lisp program, stored in the lisp memory image "games.mem". The response analysis program uses the "responder.mem" lisp memory image. The simulator starts by simply printing out the initial web page. It only runs the lisp memory image "netsim.mem" when it needs to do a real simulation.

The "games.mem" image more or less takes care of itself. It takes inputs in the form of http commands (i.e., "get URL") and produces web pages that leave URLs that, if pressed, will again call the "games.mem" image. It is programmable in the sense that new "games.mem" images can be created to augment existing functionality, and there is even a systematic way of producing these images and testing them using a simpler interface before 'burning' them into a lisp image. This will be described later in this manual.

The "responder.mem" lisp image is rather more interesting in that it contains substantial analytical capabilities that can be accessed directly from the lisp interface is so desired. It is, for example, fairly easy to create a custom analysis program using the built-in metrics and analytical capabilities. Indeed, the entire CID database contents and your own full-scale simulation engines can be created as active content from this image if so desired. Details will be provided later in this manual. The initial call to this image simply produces a standard interface the responder database. Responder needs an IP address for the URLs it provides in its web pages. Unless you do something to change it, this will be the first IP address listed in an ifconfig command. To check what it will be at any given time, type the 'myip' command into the shell. This can change if and when interfaced are configured, so you might want to consider this in providing simulator access to other computers on your network.

The above code does not even touch "netsim.mem", however, full details on how to do simulations with this memory image are provided below. The is, in essence, the same memory image used on a parallel processor to simulate more than a million attack sequences against a defensive network as published on the all.net web site. It is quite a sophisticated simulator but it can be easily run and output can be put into forms that are useful for further analysis.

Calling games.mem

I will again start with the perl script that calls these programs on the CD. In this case, we will be focussing on the calls to the games.mem lisp memory image. Again, I have reformatted for viewing and abstracted the 'important' parts.

As you can see, http get's with a URL using "RoomeMove" are transformed into 'move' calls. A "move" is simply an input to the game which is then tested against a table to produce different outputs. Outputs are generally in the form of a web page worth of text. In order to build a game, the user simply creates a set of web pages that link to each other in various ways. It is then transformed into a set of text strings and a set of 'move tables'. The game itself retains no state information. All of that is sent out in the URLs from the last move. So a user can simply send in any 'valid' URL and generate the appropriate 'response' from the game.

To quickly summarize, you 'call' games.mem by sending it an input that is in the 'moves' table and it produces an output as described by that table. If no output is designated for that move, the game will produce an appropriate page telling the user to press the 'back' button and try again. If the URL is sufficiently out of bounds, the perl script will tell the user not to try such things at this site and games.mem will never even get accessed.

Calling responder.mem

I am nothing if not consistent. Here is the perl code that is used to call the "responder.mem" lisp memory image.

The important thing to note is that it calls the memory image with an input consisting of the type of analysis to be performed (i.e., GET, predict, warnings, attacks, or response) and the inputs to that analysis ($rest). In this case, $rest consists of the results produced by the web browser's generation of a URL from a 'form'. If you select any type other than one listed, you will get an error page, probably telling you not to try that sort of thing here. The form you fill out when you use this program gives the details of how to code such a form, while the result os such coding typically looks something like this:

...23=0&41=3&3=4...

The & separates arguments, while the = sign designates an assignment of the variable number on the left to the value on the right. For example, the snippet above indicates that variable 23 is given a metric value of 0, variable 41 is given a metric value of 3, and variable 3 is given a metric value of 4. In this case, if the analysis is from attacks, the variable number corresponds to that 'attack' number in the CID database, while the metric value is the number provided by the menu selection from the user interface.

The program takes it from there. If any other character appears in the input stream, it is either ignored or treated as the end of input. Since lisp handles arbitrarily large numbers with ease, you can make any metric values you want and lisp will crunch the numbers for you. We chose 0-10 because we figured that better resolution was not likely to show up anytime soon in assessing relative importance of different things we analyze, and because it was easy to create a workable input form. The metrics grow rather rapidly as they are multiplied together and normalized relative to the maximum value. It is not unusual to get a number with 20 digits or so from this sort of analysis. If you make the inputs really big, you may run out of memory and crash your computer, but it is far more likely that you will run out of space in your IP packets. After all, a datagram can only have about 64,000 total bytes, while lisp has no problem handling numbers far larger than that. The list of variables is more limited and if you use one that is out of bounds you may get either an error message or a wrong result. In any case, the system won't do anything really bad.

Calling netsim

The netsim.mem call is by far the most interesting of these examples. In this case, the perl script calls lisp and gives it explicit lisp instructions. This means that the syntax checking in the perl script is real important for getting the right answer and an error in this can, potentially, result in remote root access to your computer. So be careful. I have removed some of the html from this example and reformatted so it looks right in this document.

The first important thing this script does is extract the input parameters. They are, $what, $attack, $strength, $from, and $to. You will notice that these are the same items entered from the form used by the user. After extracing these values, they are reformatted by removing any invalid bytes that may have been sent in by the malicious user, checking them for validity, and replacing them with valid values of my choosing if they are not valid. This is done for all parameters so that no malicious user input can remain by the time it gets to the call to the simulator.

Next, the program prints out the preliminary web page that the user sees. It then gets the current time, unpacks it into a convenient format, and sends it and the other parameters to the lisp program. The time is used as a random seed to the simulator. Choose to use a constant and you will get the same results for the same input parameters each time - good for repeatability - bad for trying to explore the simulation space. The other settings turn on detailed reporting (which you might want off for large numbers of simulations) and tell the program to simulate one attack with the values provided. After the simulation runs and produces its html output, the end of the user output page is printed and all is well.

Programming games.mem

We originally programmed the games simulator by creating a set of web pages organized in a directory tree. The tree has a set of subdirectories associated with different 'levels' in the game, and each game screen is a single html page. From each page, you select from a menu or a pushbutton of some sort, and the URL associated with that selection can either:

Case 1: A transition page

The first case might have a web page that looks like this:

In this case, the page presents some text for a scenario and a set of options held within a 'form'. The form allows the user to check off one of the possible answers. When the "go" button is pressed, the URL sent to the server corresponds to the filename of the next move. In this case, the answer that leads to "S3good" is probably better than the onw that leads to "wall".

Not all answers have to be this obvious, but there is an obvious problem. A user could look at the source code fo a web page to get hints about a better answer. In addition, these URLs don't change, so a user trying to 'win' by playing again and again can easily map out the whole game. Since these simulators are designed to run through a series of training exercises and are not designed to prevent cheating, there is no reason to get more sophistocated.

Case 2: A terminal page

The second case might have a web page that looks like this:

This particular page corresponds to the file "/rooms/S1M6" in the simulator. Since the user doesn't know which of the URLs in a given game lead where, this works the first time through a game.

Case 3: An analyzed page

The third case involves some sort of analysis to find out whether the user had the right answer. Here is an example - similarly reformatted.

In this case, we have asked the user to fill in a form. The answer will be used in a lookup table called "answers" which is referred to via the "NAME=answers-L1/AscendPass" sequence in the form for this page. Within the 'answers' file, the following line provides a correct answer for this particular entry and the linkage to the next page to be displayed:

L1/AscendPass XXXXXX L1/AscendOK

This is interpreted to mean that if the URL 'answers-L1/AscendPass' followed by a value of 'XXXXXX' is encountered in an input, the contents of the page called 'L1/AscendOK' will be displayed. I have put in the XXXXXX in place of the real answer so the game won't be ruined for those who have not yet gotten this far. If there are multiple right answers, a line can be provided for each, and if different answers lead down different paths, different response pages can be provided for them.

Another option is available for 'milti-answer' checkboxes. The line in the answers file looks like this:

Multi Straight-on-answers-Multi-Turner-on-answers-Multi-Under10 Widget/Picked

In this case I will leave it to the reader to figure out what screen in which game has what answers to fulfil this rule.

In order to convert your file-based game to a working game, simply create your own lisp source file. The file should have a series of entries that look like this:

Where the entry within the " signs in the first line corresponds to the filename and any use of a " sign in the contents of a page are replaced with \" (so the reader doesn't mistake it for the end of the entry).

If you use answers, the answers file should look like this:

Where (in this case) Sample is the name of the game, URL corresponds to the filename in the FORM, answer is the answqer to trigger this response, and action is the name of the entry to be displayed if the answer is correct.

Now that you know how it works, programming details are pretty easy to explain. A special 'loadup' form is provided to allow you to load your own lisp source file into the memory image with the result being saved in "/tmp/games.mem". All you do is run the following command with your file substituted for "sample.lsp":

A sample game (rooms) is includes in the file:

Programming responder.mem - (actually "cid.mem")

Responder provides analytical capabilities that are included for remote use in "responder.mem". This is not intended to be a modifiable version of the response process, but only an interface handler. The real capabilities are provideds in the "cid.mem" file, which makes the following available to the user:

You will likely want to be a lisp programmer to use these functions, however, they provide the underlying capabilities you will need to do more complex simulations and analysis with this database.

These are the functions defined in "cid.mem" and backed up by a database full of entries associated with them. 

defined functions:

get the data from xref and text databases
	(getxref '([TAD] # [TAD]) get xref information
	 (getxref '(T 18 A)) gets attack mechanisms used by threat 18
	(gettxt '([TAD] #))	get text for item
	 (gettxt '(T 18)) prints threat 18 data
low-level usage examples:
	(gethash '(A 83 D) xref-table)
	 (32 30 45 88 47 94 91 96 99 72 87 63 18 21 138 74 89 10 37 84 85 31 22 12 122 51 41 117 20 52 125 9) ; T
	(gethash '(A 82 D) xref-table)
	 (131 35 57 105 120 94 58 91 96 132 99 3 13 87 76 21 6 138 93 14 65 74 116 89 130 10 67 37 84 86 59 42 43 126 66 22 19 69 98 36 112 25 28 12 122 11 16 101 51 40 115 41 133 103 1 117  20 125 128 106 24 95 9 78 97 2) ;
	(union (gethash '(A 83 D) xref-table) (gethash '(A 82 D) xref-table))
	 (32 30 45 88 47 72 63 18 85 31 52 131 35 57 105 120 94 58 91 96 132 99 3 13 87 76 21 6 138 93 14 65 74 116 89 130 10 67 37 84 86 59 42 43 126 66 22 19 69 98 36 112 25 28 12 122 11  16 101 51 40 115 41 133 103 1 117 20 125 128 106 24 95 9 78 97 2)
	(intersection (gethash '(A 83 D) xref-table) (gethash '(A 82 D) xref-table))
	 (94 91 96 99 87 21 138 74 89 10 37 84 22 12 122 51 41 117 20 125 9)
	(gethash '(A 1) database-table)
	 ((NAME "errors and omissions") (DESCRIPTION "...") (COMPLEXITY "..."))
	(gethash '(D 134) database-table)
	 ((NAME "periods processing and color changes") (DESCRIPTION "...") (COMPLEXITY "..."))

The universal translator
	(x2y '([TADPSIMO] # ... #) [TADPSIMO])	relates a typed list to a different type
		so... (x2y '(A 1 2 3) 'D)	relates the listed attacks to applicable defenses
		and... (x2y '(A 1 2 3) 'T)	relates the listed attacks to applicable threats
		and... (x2y (x2y (x2y '(A 1 2 3) 'T) 'A) 'D)	relates the listed attacks to threats, other attacks, and defenses
		from there... (x2y * 'S)	gives you the related surety properties

Process properties: Prevent Detect React for defenses
	(p2d '[PDR])	(p2d '([PDR]+))
	(d2p #)		(d2p '(# ... #))

Surety properties: Integrity Availability Confidentiality Use-control for Defenses and Attacks
	(s2d '[IACU])	(s2d '([IACU]+))
	(d2s #)		(d2s '(# ... #))
	(s2a '[IACU])	(s2a '([IACU]+))
	(a2s #)		(a2s '(# ... #)))

Impact: Theory, Demonstrated, Widespread for Attacks and Defenses
	(i2a '[TDW])	(i2a '([TDW]+))
	(a2i #)		(a2i '(# ... #))
	(i2d '[TDW])	(i2d '([TDW]+))
	(d2i #)		(d2i '(# ... #))

doMain: Physical, Logical, Systemic for Attacks and Defenses
	(m2d '[PLS])	(m2d '([PLS]+))
	(d2m #)		(d2m '(# ... #))
	(m2a '[PLS])	(m2a '([PLS]+))
	(a2m #)		(a2m '(# ... #))

OrgIssues: organizational issues cross with defenses
	(o2d '[MPSRDATFNILYWGEO]) (o2d '([MPSRDATFNILYWGEO]+))
	(d2o #)		(d2o '(# ... #))

Threats to Attacks and Attacks to Threats
	(t2a #)		(t2a '(# ... #))
	(a2t #)		(a2t '(# ... #))

Attacks to Defenses and Defenses to Attacks
	(a2d #)		(a2d '(# ... #))
	(d2a #)		(d2a '(# ... #))

Pretty print items in the current language
	cite
	dd
	referto
	name
	pointto
	description
	complexity

Print a whole entry in the current language
	print-details
	(print-details (gethash '(D 134) database-table)) does a printout in the proper format defined for the 'language'.

Analyze attacks for threats, other attacks, defenses
	so... (t2a (a2t '(# ... #))) lists the attacks you might see
		from the threats that could have created the attacks you have seen
	and... (a2d (t2a (a2t '(# ... #)))) lists the possible defenses against those threats
	and... if we want to limit things in other ways, we might try...
		(intersection (t2a (a2t '(# ... #))) (i2a 'W)) ... only widespread attacks from that source
		(intersection (a2d (the last thing)) (i2d 'W)) ... only widespread defenses against those attacks
		(intersection * (p2d '(D R))) ... only detect and react of those
		(intersection * (m2d 'L)) ... only logical ones of those
		(intersection * (o2d '(M P S R D A))) ... only management, ... of those

Analyze defenses for attacks that will work and threats that can exploit them
	so... given a list of defenses in place '(d1, ..., dn)
	(d2a '(d1 ... dn))		find attack methods covered...
	(set-difference Attacks *)	find attack methods NOT covered...
	(a2t *)				find threats capable of exploiting the uncovered attack methods

Present the results
	(show '([TAD] #))	(show '([TAD] # ... #)) show the full write-up of a list of stuf (show '(T 1 2 3)) for example
	(nameof '([TADPSIMO] [# ... #]+))	list the names of the things
	so...	(nameof (list 'O (d2o (a2d (t2a (a2t '( 12 23 34 76 45))))))) lists the organizational issues to be addressed
	while... (show (list 'D (a2d (t2a (a2t '( 12 23 34 76 45)))))) details the defenses against that threat
	and... (nameof (list 'D (a2d (t2a (a2t '( 12 23 34 76 45)))))) lists the names of the defenses
	and... (show (list 'O (d2o (a2d (t2a (a2t '( 12 23 34 76 45))))))) details the organizational issues
	while
	(show (x2y (x2y (x2y (x2y '(A 12 23 34 76 45) 'T) 'A) 'D) 'O))

defined lists:
	Threats Attacks Defenses	lists of the Threat, Attack, and Defense numbers

defined variables:
	language		to tell which language to print in (html or test)

From these primatives, all of the functions of Responder are built up. In essence, we take input, check formats, do a series of transformations, and print results. IF you want different functionality, you need to write lisp routines that use these capabilities to create those functions.

Programming netsim.mem

Netsim is best left alone from a standpoint of altering its normal functions or using its functions in any manner other than for simulation. On the other hand, netsim provides a variety of useful simulation capabilities that are easily used through the simple interface provided by the SimWeb.pl script.

Netsim implements an event driven simulator. The simulator itself should not be altered if it is going to run properly, however, the things you likely would want to be able to change are included here, starting with the output language:

For producing web pages, html is a better langauge, but for producing output for automated analysis, or for debugging from a terminal, text is pretty good.

Debugging can produce a lot of messages, but it is often interesting to see how simulations operate on the inside. set it to T if you want to see a LOT of useless debugging information.

Details are desired when you want to produce outputs such as thoe produced by the web access program, but for running many simulations and collecting statistical results, details should be left off.

Detection is enabled if you want to see what happens when defenders are in place, but with detection turned off, you can do the analysis to determine how long an attacker might take to succeed without defenses in place. This is, in essence, a measure of a completely passive defense.

Analytical results are produced by filling a number of buckets representing different time periods. Plotwidth is the width of the plot. Between them they produce a wide variety of different text plots of multiple simulation runs. In out analysis for the published papers, we used this to get an idea about things of interest but ended up plotting most things using gnuplot based on the numerical results.

The default network that is simulated is described here:

It is almost certain that this is not your network, or even a good representation of it. Therefore, you should probably build a new network representation for your own network. The description above indicates a list of nodes (i.e., node), each with a (e.g. "David"), a list of defenses at that node (e.g., D (125 29 17)) where the defense numbers are the defende numbers from the CID database, and a list of links to other nodes (e.g., L ("Charlie" "David" "Edward")).

This structure can be any reasonable size and links can induce loops if this represents the topology of your network, but the more links and node and the more layers the attack has to go through, the longer the likely run time will be for large numbers of runs. This is a modelling issue that has to be addressed with any simulator.

When simulations are run, each simulation run builds a sequence of nodes it is planning to attack to get from source to destination. This is generated from the network topology using pseudo-random choices from options that move closer to the target with no loops. The simulator then tries to get through the list of intermediary targets until it succeeds or fails. This could take a long time for low probability of success attacks and poor or no detection and defense capabilities. There may even be special cases where it takes forever. Let the defense designer beware.

This example chooses one of the node sequences and schedules the first attack against that sequence. The simulation is then run once time, leaving restuls in the variable "result".

Note that the list of threats, the start and finish nodes, and the defender strength are needed in order to do this run. The next example does a sequence of 100 attack attempts, saving the results in "result" - a list of the results from all runs.

To see the results of the last run set, use this:

This example does the same thing but prints detailed results along the way:

From the shell, you can invoke these actions as follows:

The random seed: 10101110010001000100111101 can be set to any binaty value desired for different results. You cal look at the results from this run most clearly via the web browser. Try this:

Then, with your web browser, enter the URL:

file://tmp/results.html

You should see a series of runs in all their detail, followed by a set of statistics including 2 color bar charts with red and green results indicating times vs. quantity of defender wins (in green) and losses (in red) for these runs.