teuton 2.1.1 → 2.1.2

data/docs/developers/01-telnet.md

@@ -0,0 +1,121 @@
+
+# 01 - Conexión Telnet
+
+> ¡Vale, lo sé! No debería estar usando Telnet ni Windows 2012.
+> Pero ahora mismo es un reto personal y quiero descubrir qué está pasando.
+
+---
+
+# Herramientas que uso
+
+He creado el siguiente [programa ruby](../../tests/manual/telnet.rb) para abrir
+una conexión telnet a una máquina remota, ejecutar un comando y mostrar
+el resutado en pantalla.
+
+---
+
+# Gema net/Telnet
+
+Estoy usando la gema `net/telnet`, la cual en su [documentación](https://www.rubydoc.info/gems/net-telnet/0.2.0)
+pone lo siguiente:
+
+```
+# Usage
+# Log in and send a command, echoing all output to stdout
+
+localhost = Net::Telnet::new("Host" => "localhost",
+                             "Timeout" => 10,
+                             "Prompt" => /[$%#>] \z/n)
+localhost.login("username", "password") { |c| print c }
+localhost.cmd("command") { |c| print c }
+localhost.close
+```
+
+> Repositorio GitHub de la gema: https://github.com/ruby/net-telnet/
+
+---
+
+# Comprobaciones
+
+## MV GNU/Linux Debian 9 con servidor telnet
+* Manualmente -> OK
+* Usando el programa -> OK
+
+```
+Testing : {:ip=>"192.168.1.106", :username=>"root", :password=>"profesor", :cmd=>"whoami"}
+Output  : ["whoami", "root", "root@vargas42d:~# "]
+
+Testing : {:ip=>"192.168.1.106", :username=>"profesor", :password=>"profesor", :cmd=>"whoami"}
+Output  : ["whoami", "profesor", "profesor@vargas42d:~$ "]
+```
+
+## MV Windows 2008 server con servidor Telnet
+* Manualmente -> OK
+* Usando el programa -> OK
+
+```
+Testing : {:ip=>"192.168.1.115", :username=>"Administrador", :password=>"profesorFP2018", :cmd=>"whoami"}
+Output  : ["whoami", "vargas42s08\\administrador", "", "C:\\Users\\Administrador>"]
+
+Testing : {:ip=>"192.168.1.115", :username=>"profesor", :password=>"sayonaraBABY2018", :cmd=>"whoami"}
+Output  : ["whoami", "vargas42s08\\profesor", "", "C:\\Users\\profesor>"]
+```
+
+## MV Windows 2012 server con servidor Telnet
+* Manualmente -> OK
+
+```
+david@camaleon:~/proy/tools/sysadmin-game> telnet 192.168.1.114
+Trying 192.168.1.114...
+Connected to 192.168.1.114.
+Escape character is '^]'.
+Welcome to Microsoft Telnet Service
+
+login: administrador
+password:
+
+*===============================================================
+Microsoft Telnet Server.
+*===============================================================
+C:\Users\Administrador>whoami
+vargas42s12\administrador
+
+C:\Users\Administrador>
+C:\Users\Administrador>exitConnection closed by foreign host.
+david@camaleon:~/proy/tools/sysadmin-game> telnet 192.168.1.114
+Trying 192.168.1.114...
+Connected to 192.168.1.114.
+Escape character is '^]'.
+Welcome to Microsoft Telnet Service
+
+login: profesor
+password:
+
+*===============================================================
+Microsoft Telnet Server.
+*===============================================================
+C:\>whoami
+vargas42s12\profesor
+
+C:\>exiConnection closed by foreign host.
+```
+* Usando el programa -> OK
+
+```
+david@camaleon:~/proy/tools/sysadmin-game> ./tests/manual/telnet.rb
+
+Testing : {:ip=>"192.168.1.114", :username=>"Administrador", :password=>"profesorFP2018", :cmd=>"whoami"}
+Output  : ["whoami", "vargas42s12\\administrador", "", "C:\\Users\\Administrador>"]
+
+Testing : {:ip=>"192.168.1.114", :username=>"profesor", :password=>"sayonaraBABY2018", :cmd=>"whoami"}
+Output  : ["whoami", "vargas42s12\\profesor", "", "C:\\Users\\profesor>"]
+
+```
+---
+
+# Problema
+
+La aplicación falla cuando lo intento con Windows 2012 server.
+
+Creo que la estoy usando correctamente, pero hay algo que funciona diferente
+en Windows 2012 y no consigo identificar el qué.

data/docs/developers/02-ssh.md

@@ -0,0 +1,93 @@
+
+# 02 - Conexión SSH a PowerShell
+
+---
+
+# Herramientas que uso
+
+He creado el programa de ruby [ssh.rb](../../tests/manual/ssh.rb) para abrir
+una conexión SSH a una máquina remota, ejecutar un comando y mostrar
+el resutado en pantalla.
+
+---
+
+# Gema net/ssh
+
+Estoy usando la gema `net/ssh`, la cual en su [documentación](hhttp://net-ssh.github.io/net-ssh/)
+pone lo siguiente:
+
+```
+require 'net/ssh'
+
+Net::SSH.start('host', 'user', password: "password") do |ssh|
+  # capture all stderr and stdout output from a remote process
+  output = ssh.exec!("hostname")
+  puts output
+end
+```
+
+> Repositorio GitHub de la gema: https://github.com/net-ssh/net-ssh
+
+---
+
+# Comprobaciones
+
+## Debian 9 con servidor SSH
+
+Todos los comandos que se ejecutan vía SSH por esta herramienta funcionan correctamente.
+
+## MV Windows 2012 server con servidor SSH
+
+* Manualmente -> OK (usando ssh con sshpass)
+
+```
+david@camaleon:~/proy/tools/sysadmin-game> sshpass -p profesorFP2018 ssh administrador@192.168.1.114 'get-windowsfeature -name rds-rd-server'
+
+Display Name                                            Name                   
+------------                                            ----                   
+    [ ] Host de sesi�n de Escritorio remoto             RDS-RD-Server          
+
+```
+
+* Manualmente -> OK (usando ssh)
+
+```
+david@camaleon:~/proy/tools/sysadmin-game> ssh administrador@192.168.1.114 'get-windowsfeature -name rds-rd-server'
+administrador@192.168.1.114's password:
+
+Display Name                                            Name                   
+------------                                            ----                   
+    [ ] Host de sesi�n de Escritorio remoto             RDS-RD-Server          
+```
+
+* Usando el programa -> OK (Comando whoami)
+
+```
+david@camaleon:~/proy/tools/sysadmin-game> ./tests/manual/ssh.rb
+
+Testing : {:ip=>"192.168.1.114", :username=>"Administrador", :password=>"profesorFP2018", :cmd=>"whoami"}
+Output  : ["vargas42s12\\administrador\r"]
+
+```
+
+* Usando el programa -> ERROR!!!! (Comando get-windowsfeature) La salida está vacía.
+
+```
+david@camaleon:~/proy/tools/sysadmin-game> ./tests/manual/ssh.rb
+
+Testing : {:ip=>"192.168.1.114", :username=>"Administrador", :password=>"profesorFP2018", :cmd=>"get-windowsfeature -name rds-rd-server"}
+[ArgumentError] SSH on <Administrador@192.168.1.114> exec: get-windowsfeature -name rds-rd-server
+Output  : []
+
+```
+
+---
+
+# Problema
+
+La librería `net/ssh` parece que no recoge el resultado cuando se ejecuta el comando de PowerShell `get-windowsfeature -name rds-server` en Windows 2012 server.
+
+Pero si lo hago de forma manual SI funciona.
+
+¿Puede ser que algunos comandos de PowerShell no se comportan como lo hacen todos los comandos y generan
+una salida que no puede capturar bien la librería?

data/docs/developers/03-encoding.md

@@ -0,0 +1,153 @@
+
+# 03 - Encoding (Charset)
+
+---
+
+# 1. Introducción
+
+Supongamos que tenemos la siguiente instrucción de SysadminGame:
+
+`goto :host1, :exec => "whoami"`
+
+Con esta instrucción se abre una conexión remota al equipo `:host1` y se ejecuta el comando `whoami`.
+Luego el texto obtenido se guarda en una variable String que luego se convierte en un Array con cada
+una de las líneas del texto de salida del comando. Ejemplo:
+
+```
+# Si text es el texto devuelto por el comando entonces output es un Array de Strings
+output = text.split("\n")
+```
+
+La variable String de ruby trabaja con codificación 'UTF-8'. En el momento de ejecutar
+`text.split("\n")` se espera que text esté codificado 'UTF-8'. En caso contrario tenemos un error.
+
+---
+
+# 2. Problema
+
+Cuando ejecutamos:
+
+`goto :win1, :exec => "get-windowsfeature -name rds-rd-server"`
+
+siendo `:win1` un Windows 2012 server tenemos un error.
+
+Si ejecutamos el comando manualmente obtenemos la siguiente salida:
+
+```
+david@camaleon:~/proy/tools/sysadmin-game> ssh administrador@192.168.1.114 'get-windowsfeature -name rds-rd-server'
+administrador@192.168.1.114's password:
+
+Display Name                                            Name                   
+------------                                            ----                   
+    [ ] Host de sesi�n de Escritorio remoto             RDS-RD-Server          
+```
+
+Como podemos comprobar, este comando genera una salida con tildes codificada en ISO-8859-1. Y ahí están el problema.
+
+---
+
+# 3. Solución
+
+La solución que se propone es poner la siguiente instrucción en esos casos:
+
+`goto :win1, :exec => "get-windowsfeature -name rds-rd-server", :encoding => "ISO-8859-1"`
+
+Esto es, para las salidas de los comandos que requieran conversión de tipo, se debe
+especificar con `:encoding` el tipo de codificación que se recibirá. Luego ésta se convierte
+internamente a 'UTF-8' y a partir de ahí todo funcionará correctamente.
+
+---
+
+# 4. Comentarios
+
+Entiendo que es una molestia indicar la codificación en algunos comandos/servidores especiales. Pero por ahora no se puede asumir que siempre se recibirán los caracteres con la misma codificación.
+
+---
+
+# 5. ¿Cómo averiguar el encoding (charset) de forma automática?
+
+Hablando con _Albérica_, el problema anterior, ella comenta la idea de buscar la forma de encontrar el `encoding`  de forma automática. Me pongo a pensar y escribo lo siguiente:
+
+> **Leer el encoding de los ficheros y cómo cambiarlo**
+>
+> En ciertas ocasiones es necesario [cambiar el encoding de una archivo](http://lacapa8v2.blogspot.com/2012/07/como-saber-y-cambiar-el-charset.html#.XDvPZqHLfQo), Con el comando file y la opción mime se puede saber el charset de un archivo.
+> Veamos un ejemplo:
+>
+>     $ file --mime test.html
+>     test.html: text/plain; charset=iso-8859-1
+>
+> Para cambiar el charset, usaremos el comando iconv:
+>
+>     $ iconv --from-code=iso-8859-1 --to-code=utf-8 test.html > test_new.html
+
+**¿Qué pasa con la salida de los comandos de un OpenSUSE en español?**
+
+Me aseguro que tengo el sistema operativo en español:
+```
+> locale
+
+LANG=es_ES.utf8
+LC_CTYPE=es_ES.utf8
+LC_NUMERIC="es_ES.utf8"
+LC_TIME="es_ES.utf8"
+LC_COLLATE="es_ES.utf8"
+LC_MONETARY="es_ES.utf8"
+LC_MESSAGES="es_ES.utf8"
+LC_PAPER="es_ES.utf8"
+LC_NAME="es_ES.utf8"
+LC_ADDRESS="es_ES.utf8"
+LC_TELEPHONE="es_ES.utf8"
+LC_MEASUREMENT="es_ES.utf8"
+LC_IDENTIFICATION="es_ES.utf8"
+LC_ALL=
+```
+Ahora vamos a comprobar el charset de la salida de algún comando:
+```
+$ pwd > /tmp/pwd.tmp
+$ file --mime /tmp/pwd.tmp
+pwd.tmp: text/plain; charset=us-ascii
+```
+
+> Interesante... La salida de los comandos tienen charset `us-ascii`,
+a pesar de que mi sistema está en español.
+>
+> Me pregunto ¿funcionarán todos los comandos de la misma forma? Lo lógico es pensar que sí. En dicho caso podremos asumir que todos los comandos de GNU/Linux generan la salida con enconding us-ascii.
+
+**¿Qué pasa con los comandos de W2012 en español?**
+
+Averiguar el encoding que está usando por el terminal:
+```
+$ ssh administrador@192.168.1.114 'chcp' > chcp.tmp
+administrador@192.168.1.114's password:
+
+$ more /tmp/chcp.tmp
+P�gina de c�digos activa: 850
+
+$ file --mime /tmp/chcp.tmp
+/tmp/chcp.tmp: text/plain; charset=iso-8859-1
+```
+
+O sea, que según el comando tiene charser `850` y luego el resultado del comando está en `iso-8859-1`. Pero no queda claro porque hay comandos que generan la salida en una codificación y otros en otra. Veamos:
+
+```
+$ ssh administrador@192.168.1.114 'pwd' > win.tmp
+administrador@192.168.1.114's password:
+
+$ file --mime win.tmp
+win.tmp: text/plain; charset=us-ascii
+
+$ ssh administrador@192.168.1.114 'chcp' > chcp.tmp
+administrador@192.168.1.114's password:
+
+$ ssh administrador@192.168.1.114 'get-windowsfeature -name rds-rd-server' > gwf.tmp
+administrador@192.168.1.114's password:
+
+$ file --mime /tmp/gwf.tmp
+/tmp/gwf.tmp: text/plain; charset=iso-8859-1
+```
+
+> Pues la salida de los comandos de W2012 son:
+> * `us-ascii` algunas veces, y otras en
+> * `iso-8859-1`
+>
+> ¿De qué depende? ¿Qué comandos usan cada encoding?

data/docs/developers/comparative.md

@@ -0,0 +1,17 @@
+
+# Infrastructure test comparison
+
+
+| Features | Teuton | Testinfra | Goss |
+| -------- | ------ | --------- | ---- |
+| URL      | https://github.com/teuton-software/teuton | https://testinfra.readthedocs.io/en/latest/index.html | https://github.com/aelsabbahy/goss |
+| License  | GPL v.3 | Apache license 2.0 | Apache license 2.0 |
+| Programming language | Ruby | Python | Go |
+| Platforms | Multiplatform | Multiplatform | GNU/Linux |
+| Remote connections | SSH, Telnet | SSH | ? |
+| Installed on | Master | Slave |  |
+| Test Units Lenguage definition | Teuton DSL | Python | YAML |
+| Configuration input files | YAML, JSON | Python | YAML |
+| Output formats      | Documentation, TXT, YAML, JSON, silent | ? | rspecish, documentation, JSON, TAP, JUnit, nagios, silent |
+| Builtin functions | Yes | Yes | ... |
+| Function creation | Yes | ?   | ? |

data/docs/dsl/_Sidebar.md

@@ -0,0 +1,30 @@
+
+# Keywords (DSL)
+
+- [[DSL keywords]]
+
+Definition
+
+- [[group]]
+- [[target]]
+- [[goto]]
+- [[run]]
+- [[result]]
+- [[expect]]
+- [[result]]
+
+Execution
+
+- [[play]]
+- [[show]]
+- [[export]]
+- [[send]]
+
+Settings
+
+- [[get]]
+- [[set]]
+
+---
+
+- [[Home]]

data/docs/dsl/definition/expect.md

@@ -0,0 +1,56 @@
+
+## Description
+
+Compare the obtained result with the expected one. This comparation process is registered into final report.
+
+## Usage
+
+```ruby
+target 'Exist user obiwan'
+run 'cat /etc/passwd'
+expect 'root'
+```
+
+Use `expect` keyword to check output (from previous execution).
+
+## Example
+
+Let's see some examples:
+
+```ruby
+target 'Exist user obiwan'
+run 'id obiwan'
+expect 'obiwan' # Expect previous command output contains obiwan text
+```
+
+## Other uses
+
+| Command                      | Description                         |
+| ---------------------------- | ----------------------------------- |
+| expect 'obiwan'              | Expect line/s with obiwan |
+| expect ['obiwan', 'kenobi' ] | Expect line/s with obiwan and kenobi|
+| expect_one 'obiwan'          | Expect one line with obiwan |
+| expect_one ['obiwan','kenobi'] | Expect one line with obiwan and kenobi |
+| expect_none 'obiwan'         | Expect no line with obiwan       |
+| expect_none ['obiwan', 'kenobi' ] | Expect no line with obiwan and kenobi |
+
+* **expect /Obiwan|obi-wan/**, Expect line/s with Obiwan or obi-wan. This example uses regular expresions.
+
+---
+
+## Expert mode
+
+After every execution keyword (`goto`, or `run`), we get command outputs and save it into `result` object. So we can ask to `result` to create more complex evaluations.
+
+For example, if we have this execution
+```ruby
+target 'Exist user vader'
+run 'cat /etc/passwd'
+```
+
+Then we check result with
+```ruby
+expect result.find("vader").count.eq(1)
+expect result.find(/Darth|darth/).find(/Vader|vader/).count.eq(1)
+expect result.not_find('#').find(/vader).count.eq(1)
+```

data/docs/dsl/definition/goto.md

@@ -0,0 +1,112 @@
+
+## Description
+
+Connect to remote host and executes command. The commadn output is saved into result object.
+
+## Usage
+
+```ruby
+goto :host1, :exec => "id fran"
+goto :host1, :execute => "id fran"
+```
+
+> ADVISE: I know that programers dislike `goto` sentence, but this is diferent. Think of it as english speaker, not as developer.
+
+* This example connect to remote host identified by `host1`. Then we execute the command into it and save the output commadn into result object.
+* `host1` is a lbal that identifies specific machine. Host information (ip, username, password, protocol) cames from config file.
+
+## Examples
+
+Execute `id obiwan` comand into remote host `linux1`.
+```Ruby
+  goto :linux1, :exec => "id obiwan"
+  goto :linux1, :execute => "id obiwan"
+  goto :linux1, exec: "id obiwan"
+  goto :linux1, execute: "id obiwan"
+```
+
+Execute `id david` command into `localhost`.
+
+```Ruby
+  goto :localhost, :exec => "id david"
+  goto :localhost, :execute => "id david"
+  run "id david"
+```
+
+## Protocol
+
+**SSH connection**
+
+By default, when invoking `goto :host1` sentence, Teuton try to open remote SSH session. This config files examples do the same:
+
+Sample 1:
+```
+---
+:config:
+---
+:global:
+:cases:
+- :tt_members: Student1
+  :host1_ip: 1.1.1.1
+  :host1_username: student
+  :host1_password: secret
+```
+
+Sample 2:
+```
+---
+:config:
+---
+:global:
+:cases:
+- :tt_members: Student1
+  :host1_ip: 1.1.1.1
+  :host1_username: student
+  :host1_password: secret
+  :host1_protocol: ssh
+```
+
+**Telnet connection**
+
+If you need to use telnet, then it's necessary specified that into config file. For example:
+```
+---
+:global:
+:cases:
+- :tt_members: Student2
+  :host1_ip: 2.2.2.2
+  :host1_username: student
+  :host1_password: secret
+  :host1_protocol: telnet
+```
+
+**Localhost**
+
+If our hostname is localhost, or the IP is 127.0.0.X, then Teuton will assume that you want to run your command on local system, and no session is opened. This examples are the same:
+
+```
+goto :localhost, :exec => "id david"
+```
+
+And
+
+```
+run "id david"
+```
+
+**SSH to localhost**
+
+> NOTE: Only works on Teuton version >= 2.1.X
+
+If you want to open SSH session to your localhost, then force SSH protocol into your config file, like this:
+
+```
+---
+:global:
+:cases:
+- :tt_members: Student3
+  :host1_ip: 127.0.0.1
+  :host1_username: student
+  :host1_password: secret
+  :host1_protocol: ssh
+```

data/docs/dsl/definition/group.md

@@ -0,0 +1,16 @@
+
+## Description
+
+Groups targets/goals.
+
+## Usage
+
+```ruby
+group "group_name" do
+	...
+end
+```
+
+* Define a group of targets or goal. These are groups of objectives to be evaluated.
+* At least you must define one `group`, where you can define all your targets.
+* We can use `group`, as many times as we need. Usefull to group related objectives.

data/docs/dsl/definition/result.md

@@ -0,0 +1,76 @@
+
+## Description
+
+`result` saves the output from previous execution.
+It is usefull to build advanced `expect result...` sentences.
+
+* After every execution (For example, `goto :host1, :exec => "whoami"`), Teuton gets output and saves it into `result` object.
+* Use `result` object to read or filter that output.
+
+## Usage 
+
+This example get /etc/passwd file from host1, then filter lines without '#' and with '/bin/bash'.
+Count lines number and expect it to be greater that 6.
+
+```
+target "Active users number configured with bash > 6"
+goto :host1, :exec => "cat /etc/passwd"
+expect result.grep_v('#').grep('/bin/bash').count.gt 6
+```
+
+## Examples
+
+Boolean functions:
+
+| Function            | Description               |
+| ------------------- | ------------------------- |
+| `result.eq(VALUE)`  | Result equal to VALUE     |
+| `result.neq(VALUE)` | Result not equal to VALUE |
+| `result.gt(VALUE)`  | Result greater than VALUE |
+| `result.ge(VALUE)`  | Result equal or greater than VALUE |
+| `result.lt(VALUE)`  | Result lesser than VALUE  |
+| `result.le(VALUE)`  | Result equal or lesser than VALUE |
+
+Filtering functions:
+
+| Function             | VALUE type  | Description                           |
+| -------------------- | ----------- | ------------------------------------- |
+| `result.find(VALUE)` | String      | Filter lines that contains VALUE text |
+|                      | RegExp      | Filter lines that match VALUE regexp. For example `/?ello]`, filter lines with "Hello" or "hello" |
+|                      | Array       | Apply filter to every array element. For example `["Hi","Hello"]`, filter lines with "Hi" or "Hello". |
+| `result.grep(VALUE)` |             | Same as find |
+| `result.not_find(VALUE)` |         | Filter lines that not contains VALUE. VALUE may be String, Regular Expresion or an Array. |
+| `result.grep_v(VALUE)` |           | Same as not_find |
+| `result.count`       |             | Count lines from result and save this number into result object. |
+| `result.restore`     |             | Restore result data. After every filtering action result is modified, but this function restore data to their original state. |
+
+Information functions:
+
+| Function             | Description |
+| -------------------- | --------------------------------- |
+| `result.value`       | Return first output line or value |
+| `result.content`     | Return all output lines         |
+| `result.alterations` | Return transformations applied to the output |
+| `result.debug`       | Print the result content on screen. Usefull for debugging process |
+
+## Expert use
+
+It's posible contenate a sequence of several results orders. Examples:
+
+Supose we execute this:
+```
+goto :host1, :exec => "cat /etc/passwd"
+```
+And then we could do:
+* Get all lines that dosn't contain "nologin" and contain "/bin/bash"
+```
+result.grep_v("nologin").grep("/bin/bash")
+```
+* Count all lines that dosn't contain "nologin" and contain "/bin/bash"
+```
+result.grep_v("nologin").grep("/bin/bash").count
+```
+* Return true if the number when count all lines that dosn't contain "nologin" and contain "/bin/bash" is greater than 0
+```
+result.grep_v("nologin").grep("/bin/bash").count.gt 0
+```