https://github.com/crashappsec/cap10
Script, capture and replay terminal sessions
https://github.com/crashappsec/cap10
expect linux macos pty recorder terminal
Last synced: 5 months ago
JSON representation
Script, capture and replay terminal sessions
- Host: GitHub
- URL: https://github.com/crashappsec/cap10
- Owner: crashappsec
- License: apache-2.0
- Created: 2023-11-01T16:09:45.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2023-12-05T17:33:44.000Z (over 2 years ago)
- Last Synced: 2024-01-26T23:38:21.404Z (over 2 years ago)
- Topics: expect, linux, macos, pty, recorder, terminal
- Language: Nim
- Homepage:
- Size: 60.5 KB
- Stars: 7
- Watchers: 7
- Forks: 0
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Cap10
## Script, capture and replay terminal sessions
You record and play back terminal sessions or other terminal programs
with the `cap10` command, which will record a process until it exits.
Cap10 will automatically remove long pauses in your input stream. So
type as slow as you want... walk away and come back an hour
later. You're good.
- `cap10 record [optional command]` starts recording.
- `cap10 play file.cap10`
- `cap10 convert [filename]` will convert a cap10 file to the _asciicast 2.0_ format.
The `cap10` capture format is binary, and there's currently not a web
player for it. But you can convert it to asciicast format.
On Linux, cap10 should build as a static ELF binary, so can run in
minimal environments like Alpine, without the Python dependencies of
asciinema.
Also, we produce a separate input log to make it easier to automate
scripting for demos (in conjunction w/ our expect capabilities
below). It captures keypresses only, so if you don't type out a full
command, it won't capture the exact commands (in the future we may do
some shell integration to get the shell view).
Essentially, cap10 should replace the following tools:
- script
- asciinema
- expect
- autoexpect (which never worked well anyway)
## GIF conversion
If you'd like to convert the output to a video for a web page, instead
of an Asciicast, we recommend producing an GIF, which you can do
do this by exporting to asciicast and then running the
[agg tool](https://github.com/asciinema/agg) from asciinema.
## Expect More
You can also use `cap10` as an expect-like library, with the added
benefits:
1. You can fully capture your `expect` sessions if you want.
2. You can interact with your scripts if you want.
3. You can capture the input from your interactions.
The second makes expect-like automation easier to write. I've had many
cases where the regexp didn't fire, and the result was a hanging
process, with a long iteration cycle to test. Here, you can just
manually enter input, which will generate output that runs through the
pattern matcher.
For example, the below code waits for a prompt, runs a command, then
waits for 'hiho' followed by the enter key (The enter key generates
'\r' NOT '\n'; the log file does translate them back to '\n' to be more
human readable).
But the code never does anything to send that string to the
terminal. Instead, you're left to manually interact with it, and when
the pattern is matched, the 'expect' call returns.
The `passthrough` flag specifies that the user should be able to
interact. At some point, we'll expose the ability to turn this on and
off at will, and to provide more control over tty settings.
```
import cap10
var s: ExpectObject
s.spawnSession(captureFile = "expect.cap10", passthrough = true)
s.expect(".*\\$ ")
s.send("~/dev/chalk/chalk")
s.expect("hiho\r")
s.send("exit")
s.expect("eof")
echo "Capture saved to: ", s.capturePath
```
## The switchboard
At some point, we'll package this up as a library with bindings to
other languages.
Underlying everything is an IO multiplexing system that allows us to
abitrarily (and dynamically) route output from file descriptors to
other file descriptors, callbacks, etc, all without the need for
threads. We've got a bunch of little utilities we'd like to see on top
of this, that we may eventually add.
## Status
It's early, and there are some rough edges (for instance, if there are
file perms issues, we're currently not handling gracefully). This was
done for our internal use, but eventually we will polish this
up. Until then, use at your own risk :)
In the not too distant future, we'll bundle the API for direct calling
from other languages, with wrappers for (at least) Go and Python.
Eventually, we'd like to have a native player and more, and be able to
natively produce GIFs. But no hurry; the asciinema tools there are
good.
## Building
You need to have Nim 2.0 installed, and be on a 64-bit posix
system. We really develop only on Linux and Mac, so there's more than
a non-zero chance that *BSD or WSL won't work at this point...
But all you should need to do to build the `cap10` binary is run from
the root of the repo:
```
nimble build
```