102 lines
3.0 KiB
Markdown
102 lines
3.0 KiB
Markdown
# XNeedle
|
|
|
|
A simple tool for injecting faults into XML documents.
|
|
|
|
## Description
|
|
|
|
The purpose of the tool is to hide a metaphorical "needle in a haystack"
|
|
in large XML files, such as an EtherCAT SubDevice Information or ESI file.
|
|
Therefore it is a FIT (fault injection test) tool, but can be used off-label.
|
|
|
|
To live up to its name, XPath is utilized to specify precise locations
|
|
combined with a good enough set of instructions to do CRUD operations.
|
|
|
|
As the main application lies with injecting faults into ESI files,
|
|
additional functions for calculating checksums are included.
|
|
This allows recalculation of CRC32 secured sections of a given document,
|
|
such as modules in an ESI file.
|
|
|
|
## Language Specification
|
|
|
|
The XNeedle language consists of three distinct parts.
|
|
|
|
1. Expressions
|
|
|
|
Expressions may consist of function calls, arithmetic operations, sting concats
|
|
and values.
|
|
|
|
This example prepends the existing inner text of a given node with "Faulty '",
|
|
and appends the evaluated string "': 2+2=10".
|
|
```
|
|
text("Faulty '" .. text() .. "': " .. string(1+1^2) .. "+2=10");
|
|
```
|
|
|
|
2. Rules
|
|
|
|
A rule consists of a selector and a block.
|
|
The selector is using XPath to select any amount of nodes,
|
|
for which the block is applied to.
|
|
A block however can consist of multiple expressions, nested rules or bangs.
|
|
|
|
This example sets the text and an attribute based on their respective selectors.
|
|
```
|
|
$("//Device/Type[@ProductCode='#x0B583052' and @RevisionNo='#x00110000']/..")
|
|
{
|
|
$("Type") { attr("ProductCode", hex(0xDEADBEEF)); }
|
|
$("Name[@LcId='1033']") { cdata("LE2904, 4 Ch. Danger Output 24V, 0.5A, TwinUNSAFE"); };
|
|
}
|
|
```
|
|
|
|
3. Bangs
|
|
|
|
Bangs are special function calls which take either a string or XPath as parameters,
|
|
and make structural changes to the document.
|
|
They are prefixed with, as the name implies, an exclamation mark.
|
|
|
|
This example adds, removes and swaps nodes.
|
|
```
|
|
$("RxPdo/Index[.="#x1600"]/..")
|
|
{
|
|
# Modify name
|
|
$(Name) { text("FSoE Outputs"); }
|
|
|
|
# Select the Entry/Index #x7000 and change it to #x9001
|
|
$(Entry/Index[.="#x7000"]) { text("#x9001"); }
|
|
|
|
# Select the Entry with Index #x7001 and SubIndex 4, remove it
|
|
$(Entry/Index[.="#x7001"]/../SubIndex[.="4"]/..) { remove(); }
|
|
|
|
# Select the 3rd Entry
|
|
$(Entry[3])
|
|
{
|
|
# Add a tag before the above selection
|
|
!before("Entry")
|
|
{
|
|
# Add these tags with their contents respectively
|
|
!add("Index") { text("#x4711"); };
|
|
!add("SubIndex") { text("3"); }
|
|
!add("BitLen") { text("256"); }
|
|
!add("Name") { text("Garbage"); }
|
|
!add("DataType") { text("UINT"); }
|
|
}
|
|
}
|
|
# Swap Entries
|
|
swap("Entry[3]", "Entry[4]");
|
|
}
|
|
```
|
|
|
|
4. Comments
|
|
|
|
Comments are prefixed with the '#' character.
|
|
|
|
|
|
## Running the command
|
|
|
|
```bash
|
|
xn sample.xn -i input.xml -o output.xml
|
|
```
|
|
The file `sample.xn` is the transformation specification as outlined above.
|
|
For input and output, see `input.xml` and `output.xml` respectively.
|
|
|
|
Refer to the help text using the `--help` switch for more details.
|