Please review any and all PUBLIC repositories, groups and associate files. These allow anyone on the Internet to access without authentication. Repository and group owners are responsible for their content and permission settings. Go to your project(s), click on Settings > General and expand the "Visibility, project features, permissions" to change this setting.

readme.md 4.85 KB
Newer Older
1 2
# Monterey Phoenix - Trace Generator

McCullick, Philip (CIV)'s avatar
McCullick, Philip (CIV) committed
3 4 5 6 7
The "Monterey Phoenix System and Software Behavior Modeling Tool" is the source code for the computational engine for MP. Currently, the code runs on Mac and Linux operating systems. 
 
Rewriting this code according to your own style may be tempting, but be forewarned about the amount of time and level of challenge involved in such a task. This code is a product of over a decade of development, refinement and optimization. Please consider carefully any ideas for changes you have for this code, given it was shaped by many different angles of attack over the years.  There is a reason behind every implementation decision.  The heuristic “Simplicity does not precede complexity, but follows it” has been applied (Alan Perlis, Epigrams on Programming, http://www.cs.yale.edu/homes/perlis-alan/quotes.html).   
 
That being said, this code is put forth to invite creativity, ingenuity and fresh perspectives from the larger community to make it the best it can be.  We welcome your ideas for improvement!  You should, of course, have experience with MP modeling from a user perspective before diving into development.  There is an in-depth MP Manual available, a 2-hour MP-Firebird tutorial, and 40+ preloaded MP model examples on MP-Firebird under the Import menu.  These resources are linked from the MP website at https://wiki.nps.edu/display/MP/Monterey+Phoenix+Home.
McCullick, Philip (CIV)'s avatar
McCullick, Philip (CIV) committed
8

McCullick, Philip (CIV)'s avatar
McCullick, Philip (CIV) committed
9 10 11
### Note for developers
This repository uses a centralized workflow.  The master branch is the default development branch and represents the "gold standard” implementation approved by the core MP development team.  This repository is currently being maintained by Mikhail Auguston (NPS Professor Emeritus) and Mike Collins (Laboratory for Advanced Cybersecurity Research).  

McCullick, Philip (CIV)'s avatar
McCullick, Philip (CIV) committed
12
Monterey Phoenix is released under a [permissive open source license](LICENSE.txt)
McCullick, Philip (CIV)'s avatar
McCullick, Philip (CIV) committed
13

14 15 16 17 18
To pull a copy of the code without an NPS gitlab account, use the HTTPS protocol:
```
git clone https://gitlab.nps.edu/monterey-phoenix/trace-generator.git
```

19 20
## Setup/Requirements
* C++ compiler
21
* Bash compatible command line
22

23
## How to Run Trace Generator
24 25 26 27 28 29 30
The event generator can be run using the rall.sh script in the build folder:
```bash
./Code/rall.sh [mp_filepath] [scope]
```
- mp_filepath should be the location of the MP file that you want to process
- scope is the number of repetitions, use higher values with caution

31
There are example MP files in the Firebird_Pre_loaded_examples folder. To build those files, run a command like this:
32 33 34 35
```bash
./Code/rall.sh ./Firebird_Pre_loaded_examples/Example01_simple_message_flow.mp 1
```

36 37 38
The event generator results will be saved in the output folder as a json file with the same name as the input MP filename. 

## Overview
39
The Trace Generator uses Rigal to convert the MP file rules into C++ code which is then executed to generate the JSON output. The "rc" command runs the Rigal compiler and generates the .rsc tree. The "ic" command runs the Rigal interpreter which converts the tree into C code. 
40

41
Here is the step by step process which matches the numbering in **Code/rall.sh**:
42
1. Compile the MP2-parser.rig 
43 44
   - Creates **MP2-parser.rsc** which is the compiled Rigal code 
   - Creates **xd** script which will be used to cleanup the results
45
2. Run the interpreter on the MP2-parser.rsc with the inputs from the user MP file and scope. 
46 47
   - Creates **tree** file
   - Output on this interpreter is redirected by the script to **temp.out**. So any program output and errors will be found there. 
48
3. Compile the MP2-generator.rig
49
   - Creates **MP2-generator.rsc** which is the compiled  Rigal code
50
4. Run the interpreter on the MP2-generator.rsc with the **tree** input from the previous interpreter
51 52
   - Creates **{Your MP file}.cpp**
   - Output on this interpreter is redirected by the script to **temp2.out**.  So any program output and errors will be found there.
53
5. Run the C++ compiler on **{Your MP file}.cpp**
54
   - Creates **{Your MP file}** compiled C++ 
55
6. Run the compiled C++ program
56 57
   - Creates **{Your MP file}.json** 
   - Output on this program is redirected by the script to **{Your MP file}.txt**.  So any MP output and errors will be found there.
58 59 60 61 62 63 64 65 66 67 68

 For the detailed documentation about how the MP parser works, look at the [Documentation/MP_implementation_notes.pdf](Documentation/MP_implementation_notes.pdf).

## Documentation
* [User Documentation on Wiki](https://wiki.nps.edu/display/MP/Monterey+Phoenix+Home)
* [Documentation/MP_implementation_notes.pdf](Documentation/MP_implementation_notes.pdf) - Detailed overview of how the original script for running the Trace Generator works
* [Documentation/MP-syntax-v4.pdf](Documentation/MP-syntax-v4.pdf) - MP Language Manual
* RIGAL programming language
* [Documentation/JSON_file_structure.pdf](Documentation/JSON_file_structure.pdf)
  - [RIGAL/p61-auguston.pdf](RIGAL/p61-auguston.pdf)
  - [RIGAL/Rigal_LNCS-1991.pdf](RIGAL/Rigal_LNCS-1991.pdf)
McCullick, Philip (CIV)'s avatar
McCullick, Philip (CIV) committed
69