Add files via upload

README.md

@@ -1 +1,48 @@
-# preTDQCDebugger
+# csDbg Specification
+
+The CSD Remote Debugger (csDbg) is a learning project intended to prepare an
+uncertified developer for the Basic Skill Level Exam. The project should be
+guided by a mentor and developed by the mentee developer.
+
+## Goal
+
+The goal of the project is to implement a remote debug service that 
+interacts with a user client over a custom protocol. The debug service should
+be able to attach to or start a process on the same machine that it is 
+currently running on and communicate process state and information with client
+(contents of registers, memory address, etc.).
+
+## Overview
+
+The service (`csdbgd`) will be written in C and reside on the system with the
+executable to be debugged (referred to as the `target` executable). Refer to
+the [service specification](csdbgd.md) document for the full service 
+specification.
+
+The client will initially be implemented as a command line Python application
+(`csdbgclient.py`) but will optionally be extended into a web service 
+implemented in a common web framework like Django or Flask that supports a full
+GUI display of the debugging information of the target. Refer to the 
+[client specification document](csdbg-client.md) specification for the full
+client specification.
+
+The custom protocol (`csdbgp`) will be implemented over TCP on port 1337. Refer
+to the [protocol specification](protocol.md) document for the full 
+specification of the protocol.
+
+## Learning Tasks
+
+The csDbg project will be implemented in incremental stages called "learning
+tasks". You can all of the learning tasks in the 
+[Learning Tasks](learningtasks/) directory of this repository. It is 
+recommended that the mentor assigns the learning tasks in order as the mentee
+progresses through the project. 
+
+There is nothing wrong with doing learning tasks out of order - the learning 
+tasks progress in order of ease, from simplest to most complex. In an actual 
+project, it's often advisable to do the most complex tasks upfront, and finish
+with the simple cosmetic tasks. The learning tasks of this project progress in
+the order that they do for the purpose of teaching, not for the purpose of
+shipping a working product.
+
+Start at [Learning Task 1](learningtasks/task1.md)

csdbg-client.md

@@ -0,0 +1,3 @@
+# csDbg Client Specification
+
+Full specification coming soon

csdbg-service.md

@@ -0,0 +1,48 @@
+# csDbg Service Specification
+
+The CSD Remote Debugger implements a service in C. This service executable is
+named `csdbgd` and listens for a connection for the CSD Remote Debugger client
+component.
+
+All communication of state of the target program and receiving commands from
+the user will be over the [csDbg protocol](protocol.md)
+
+## Features
+
+Features of the csDbg service are:
+* Start an program and begin debugging at its entry point
+* Query list of pids and program names for all running processes, allowing the
+  client to select one to attach to
+* Attach to a running program identified by its pid (requires service run with
+  root privileges)
+* Set a breakpoint in the program at a specified address
+* Enable or disable breakpoints
+* View all breakpoints
+* Delete breakpoints
+* View register contents when target program is stopped
+* Set register contents when target program is stopped
+* View memory contents when target program is stopped
+* Set memory contents when target program is stopped
+* Communicate signals received that cause the target program to stop
+* Continue execution of the target program
+* Kill target program
+
+## Constraints
+
+Initial support of the csDbg is only for x86 64 bit programs running on Linux.
+* Only general purpose registers supported in initial release (no floating
+  point registers)
+* Position Independent Executables (PIE) are not supported - code addresses
+  of the target text segment should be static (this will be one of the first
+  fixes in future releases)
+* Multi-threaded programs are not supported
+
+## Future Work
+
+Prioritized:
+* Support PIE binaries by calculating offsets from the target text segment
+* Support x86 32-bit binaries
+* Parse symbol table for function names to break at start of function
+* Support multi-thread programs
+* Support ARMv7 binaries (when service is compiled as ARM binary - not
+  emulated)

learningtasks/task1.md

@@ -0,0 +1,69 @@
+# Learning Task 1
+
+## Learning Objectives
+
+* Fork a GitLab repository
+* Implement Python command line argument parsing
+* Implement Python TCP network sockets
+* Implement Python debug print options
+
+## Issues
+
+* Locate the `csdbg-client` repository on GitLab and create a branch named
+  `<your name>-master` (e.g. `kellas-master`).
+* Create the file `csdbg.py` and implement the following functionality
+  using Python 3.5 or newer:
+    * Parse the following arguments from the command line: `--ip <IP address>`,
+      `--target <target executable>`, `--pid <pid number>`, and 
+      `-v | --verbose`
+    * Ensure that the IP address is always provided, but that only one of the
+      two options of target executable and pid are provided.
+    * Print out the provided IP address and either the file name provided or
+      the process ID provided
+    * Send a TCP packet to the input IP address on port 1337 according to the
+      [protocol specification](#Protocol) below
+    * If the `-v` or `--verbose` flag is provided, print the hex encoded
+      contents of the protocol data before it is sent.
+
+## Protocol
+
+The csdbg protocol will evolve as more tasks are implemented, but for Learning
+Task 1, the protocol will be very simple:
+
+magic bytes (4 bytes): 0x6373db67
+
+message type (1 byte): initiate session - 0x00
+
+session start type (1 byte): if pid was provided - 0x00; if target executable 
+was provided - 0x01  
+
+data (variable): if pid was provided - 4 byte pid; if target 
+executable was provided - 1 byte string length of the target executable name, 
+followed by ASCII encoded target executable name  
+
+Example:
+
+If the user provides the following input:
+```
+$ python3 csdbg.py --ip 127.0.0.1 --target /bin/ls
+```
+
+Then the program should output a TCP packet sent to 127.0.0.1:1337 of the 
+following form:
+
+| Magic Bytes | Message Type | Start Session Type | Data - String Length | Data - String |
+|-------------|--------------|--------------------|----------------------|---------------|
+| 0x63 0x73 0xdb 0x67 | 0x00 | 0x01 | 0x7 | 0x2f 0x62 0x69 0x6e 0x2f 0x6c 0x73 |
+
+
+If the user provides the following input:
+```
+$ python3 csdbg.py --ip 127.0.0.1 --pid 1234
+```
+
+Then the program should output a TCP packet sent to 127.0.0.1:1337 of the
+following form:
+
+| Magic Bytes | Message Type | Start Session Type | Data - Pid |
+|-------------|--------------|--------------------|------------|
+| 0x63 0x73 0xdb 0x67 | 0x00 | 0x00 | 0x00 0x00 0x04 0xd2 |

learningtasks/task2.md

@@ -0,0 +1,20 @@
+# Learning Task 2
+
+## Learning Objectives
+
+* Unit testing in Python
+
+## Issues
+
+* Read about the Python `unittest` module 
+  [here](https://docs.python.org/3.5/library/unittest.html) and
+  [here](https://docs.python-guide.org/writing/tests/). Start thinking about
+  how you would unit test the code that you wrote in Learning Task 1.
+* In the `csdbg-client` repository, create a directory called `test/unit/`.
+  Create a file in that directory called `test_csdbg.py`. Implement
+  unit tests using the Python `unittest` module to achieve as much code
+  coverage as you can for the code that you wrote in Learning Task 1.
+* Rewrite any code that you wrote in Learning Task 1 that requires refactoring
+  to make for easier test cases.
+* Use the `unittest.mock` functionalities to mock out any dependencies of your
+  functions.

learningtasks/task3.md

@@ -0,0 +1,52 @@
+# Learning Task 3
+
+## Learning Objectives
+
+* Implement C service
+* Implement C TCP network sockets
+* Building a C program with a Makefile
+
+## Issues
+
+* Locate the `csdbg-service` repository on GitLab and create a branch named
+    `<your name>-master` (e.g. `kellas-master`) and implement the following
+    functionality in C as a file named `csdbgd.c` (note the trailing 'd'):
+    * Create a socket that listens for and accepts TCP connections on port
+      1337.
+    * Receive the `csdbg-protocol` `session initiate request` message 
+      (implemented in the python client in [Learning Task 1](task1.md).
+    * Print to the command line either: the pid or the target binary name
+      requested in the `session initiate request` message.
+    * Respond to the client with a `session initiate acknowledge` message
+      (described below).
+    * Create debug print statement that prints the bytes of the message prior 
+      to transmission.
+* Create a Makefile in the same directory that builds you C program with `gcc`
+  when the command `make` is executed. 
+    * Implement a `make clean` command that removes any build files as well.
+* Remember to follow the CSD C style guide (found on the `cybbh` GitLab) as
+  you go.
+
+## Protocol
+
+An acknowledge message should be sent from the service to the client if
+a valid `session initiate request` message is received and the debugger is
+able to debug the requested target. For now, the task is to just implement
+the receiving of a valid request message, parsing it, and immediately sending
+an acknowledgement message (later tasks will involve starting or attaching to
+the requested target program).
+
+A `session initiate acknowledge` message is described in 
+[Protocol](../protocol.md). In summary:
+* `magic_bytes` field stays the same - `0x63 0x73 0xdb 0x67`
+* `message_type` field will be set to `0x01` to indicate acknowledgement
+* `session_id` field will be a unique value for each connection. You will need
+  to implement this in a way that is managed per connection.
+* `target_architecture` field should be set to `0x01` representing that your
+  service is deployed on a host system that is a 64 bit x86 architecture
+
+Your service should respond to your client with the following:
+
+| Magic Bytes | Message Type | Session ID | Target Architecture |
+|-------------|--------------|------------|---------------------|
+| 0x63 0x73 0xdb 0x67 | 0x01 | Variable - 4 bytes | 0x01 |