adpllc/altruistic-angelshark

This project makes automating over one or more Communication Managers easier via OSSI over SSH.

Altruistic Angelshark

Altruistic Angelshark is a project devoted to making Communication Manager (ACM) automation easier. It uses the OSSI protocol over SSH to run user commands on one or more configurable ACMs. This functionality is exposed as a developer library (libangelshark), a command line application (angelsharkcli), and an HTTP daemon (angelsharkd).

Detailed User Guides

These guides give an overview of the end-user Angelshark applications, their capabilities, and common use cases. It assumes the user has familiarity with using a shell and the command line. Most commands are formatted for *nix. They should all be directly translatable to Windows, just make sure you're using (for example) angelsharkcli for *nix and angelsharkcli.exe for Windows.

• angelsharkcli: a command line application for running OSSI-formatted commands on one or more ACMs and parses the output data into useful formats (CSV, JSON, etc.)
• angelsharkd: a HTTP service for running OSSI-formatted commands formatted in JSON on one or more ACMs, by one or more clients

Installation

angelsharkcli is available as a prebuilt binary for many platforms in the GitHub releases. To install angelsharkcli from source, use cargo:

cargo install --git https://github.com/adpllc/altruistic-angelshark.git angelsharkcli

To install angelsharkd from source:

cargo install --git https://github.com/adpllc/altruistic-angelshark.git angelsharkd

Quick Examples

Get the numbers and names of all stations on a single ACM via the CLI.

$ printf 'a03\nclist stat\nf8005ff00\nf8003ff00\nt\n' | angelsharkcli print
17571230001    Arnold, Ray
17571230002    Muldoon, Robert
17571230003    Panic Rm. 1

Check three ACMs for a station and print it as JSON via the CLI.

$ angelsharkcli print --format json <<EOF
a01
a02
a03
clist stat 17571230000
f8005ff00
f8003ff00
t
EOF
[
  [
    "17571230000",
    "Nedry, Dennis",
  ]
]
angelsharkcli: ossi (02): 1 00000000 29cf No records match the specified query options
angelsharkcli: ossi (01): 1 00000000 29cf No records match the specified query options

Do the same thing over HTTP with curl.

$ nohup angelsharkd &
nohup: ignoring input and appending output to 'nohup.out'
$ curl -X POST http://localhost:8080/ossi -H 'Content-Type: application/json' -d '[
    {
        "acms": [
            "lab",
            "04",
            "11"
        ],
        "command": "list stat 17576123489",
        "fields": [
            "8005ff00",
            "8003ff00"
        ]
    }
]'

[
    {
        "acm": "01",
        "command": "list stat 17571230000",
        "error": "1 00000000 29cf No records match the specified query options",
        "fields": [ "8005ff00", "8003ff00" ],
        "datas": []
    },
    {
        "acm": "03",
        "command": "list stat 17571230000",
        "error": "",
        "fields": [ "8005ff00", "8003ff00" ],
        "datas": [
            [
                "17571230000",
                "Nedry, Dennis"
            ]
        ]
    },
    {
        "acm": "02",
        "command": "list stat 17571230000",
        "error": "1 00000000 29cf No records match the specified query options",
        "fields": [ "8005ff00", "8003ff00" ],
        "datas": []
    }
]

$ cat nohup.out
[2021-10-12T19:34:55Z INFO  angelsharkd] Starting server on 127.0.0.1:8080 ...
[2021-10-12T19:35:44Z INFO  warp::filters::log] 127.0.0.1:49366 "POST /ossi HTTP/1.1" 200 "-" "curl/7.71.1" 4.2123963s

Why should I use Angelshark? Why might it be preferable to ASA or other projects?

• Angelshark is cross-platform. It is available for Windows, Mac OSX, Linux, and FreeBSD. Angelshark should run on anything that can compile it. If statically linked, no runtime dependencies are required.
• It requires no graphical desktop to generate the same output as ASA, making it more versatile for servers or containers.
• Angelshark executables are super-fast binaries and commands are run in parallel across multiple ACMs to deliver output faster.
• Angelshark does not need or use waits or timeouts (such as one would see with expect scripts).
• Angelshark can parse ACM output data into a variety of useful formats including tab-delimited (TSV), CSV, and JSON.
• The command line is easily scripted with login configuration, command files, and task schedulers such as Cron. It outputs tab-delimited data by default, making it friendly for sed, grep, and awk.
• It is extensible, allowing developers to use the daemon or the library to write their own software on top of Angelshark!
• Angelshark uses libssh internally and will work on platforms without an SSH client, such as OpenSSH.

                                                  `r***`
                                                _i?`  .|v-
                                              <x>        ^x:
                                            rx_            =]~  `-'
                                _^**^**=` -V,                X]*<!~^*r*
:r*:                        rr**"      '<*n                 ,nl`?#i   `}~   *_
H  _r?r`                   (~                                 i"_n,     l~~|?
5     `*(r`            ``'_P`                                         <` 0_
P        `*^^^^^^^^^^^>!=:,-`'-,,:=!~><<^^^^**^^^^<<~~!=:,,-'`        !i H
5          `````.''-__,,,::"                                          =.-q^*x
H      :rrr>~!!==::,,,_--'.Z                                , y`6@=    -e`  r`
xr=**rr"                   n_                               ??"!~]`  !|?
 ..                        `}r:`         '(`                 ,Hx^^^^*-
                              -<***^^^^r(<H`                 }<
                                      `   :(r~`            '2,
                                             `<****=`    `vv
                                                   .!*^^^r`

altruistic-angelshark's Issues

Monitor BCMS Skill renders JSON mess

The monitor bcms skill command seems to dump all of the output as a single record in JSON format. Is this due to the formatting of the output, or something internal in the JSON parser?

Display alarm command appears to ignore the field values

I am able to use the fields array in the commands to filter everything so far, except for the display alarms command. If I sent the command string:

[{"acms": ["CM01"],"fields": ["0002ff00", "0004ff00", "0005ff00"],"command": "display alarm"}]

I get back

[{
"acm": "CM01",
"command": "display alarm",
"error": "",
"fields": ["0001ff00", "0002ff00", "0003ff00", "0004ff00", "0005ff00", "000cff00", "000dff00", "4e21ff00", "000eff00", "0006ff00", "0007ff00", "0008ff00", "000fff00", "0009ff00", "000aff00", "000bff00"],
"datas": [
["S000775", "DIG-IP-S", "n", "5428", "WARNING", "OUT", "", "", "06", "14", "17", "20", "00", "00", "00", "00"]
]
}]

I have tried other display commands and they seem to work just fine.

I have also tried the variant:
[{"acms": ["CM01"],"fields": ["0001ff00"],"command": "display alarm"}]
just to test, but I got back the same data set.

Thoughts on what I am missing here?

`angelsharkd` throws 400 for perfectly valid request

Angelshark Daemon is expecting datas to be arrays of arrays of strings instead of arrays of strings as written in the docs and used internally.

This was caused by a typo in the request DTO during refactoring.

Allow users to extend the daemon with their own warp filters

This will allow for additional, domain-specific functionality to be added to the daemon easily. For example, if a user wants to be able to perform a station search, instead of just running a command, they can add the relevant warp filter to route traffic to that endpoint and execute their own code. These should be opt-in with feature flags.

With no subcommands, runner and OSSI errors aren't printed

altruistic-angelshark/angelsharkcli/src/main.rs

Line 142 in 9a940e6

.context(format!("angelsharkcli: ossi ({})", name))

This line is the culprit. The format string should include the provided error. This should also apply to the runner eprintln a few lines above.

Allow for authentication via `ssh-agent` in the CLI

Having the option to use a system's ssh-agent would be a nice way of handling other key exchange algorithms, key-based authentication, and interactive passwords. It would also allow users to forbid keeping their passwords in plaintext.