Main class for configuring and running libclues. More...

#include <Engine.hxx>

Public Types
enum class	FormatFlag : uint64_t { FD_INFO = 1 }

using	FormatFlags = cosmos::BitMask<FormatFlag>

Public Member Functions
	Engine (EventConsumer &consumer)
	Creates a new Engine that reports events to `consumer`.

virtual	~Engine ()
	Tear down any tracees.

TraceePtr	addTracee (const cosmos::ProcessID pid, const FollowChildren follow_children, const AttachThreads attach_threads, const cosmos::ProcessID sibling=cosmos::ProcessID::INVALID)
	Add the given `pid` as tracee.

TraceePtr	addTracee (const cosmos::StringVector &cmdline, const FollowChildren follow_children)
	Create a new child process to be traced.

void	trace ()
	Enter the tracing main loop and process tracing events.

void	stop (const std::optional< cosmos::Signal > signal)
	Stop tracing any active tracees.

FormatFlags	formatFlags () const

void	setFormatFlags (const FormatFlags flags)
	Change formatting behaviour for system calls.

Protected Types
enum class	Decision { RETRY , DROP , STORE , DONE }
	Different decisions what to do with ptrace events. More...

using	TraceeMap = std::map<cosmos::ProcessID, TraceePtr>

using	EventMap = std::map<cosmos::ProcessID, cosmos::ChildState>

Protected Member Functions
void	checkCleanupTracee (TraceeMap::iterator it)

void	checkUnknownEvents ()

Decision	handleEvent (const cosmos::ChildState &data)

void	handleNoChildren ()

Decision	checkUnknownTraceeEvent (const cosmos::ChildState &data)
	Check the given trace event if we can make sense of it.

bool	tryUpdateTraceePID (const cosmos::ProcessID old_pid, const cosmos::ProcessID new_pid)

void	handleAutoAttach (Tracee &parent, const cosmos::ProcessID pid, const cosmos::ptrace::Event event, const SystemCall &sc)
	Invoked by a Tracee once a new child process is auto-attached.

TraceePtr	handleSubstitution (const cosmos::ProcessID old_pid)
	Invoked by a Tracee when multi-threaded execve() leads to substitution of a PID by another.

Protected Attributes
TraceeMap	m_tracees
	Currently active tracees.

EventMap	m_unknown_events
	Unknown ptrace events stored for later processing.

cosmos::ProcessID	m_newly_attached_pid = cosmos::ProcessID::INVALID
	The PID of a newly auto-attached Tracee, if any.

EventConsumer &	m_consumer

FormatFlags	m_format_flags
	Format settings for all tracees attached to this engine.

Friends
class	Tracee

Detailed Description

Main class for configuring and running libclues.

This is the main class for configuring Tracee's and actually performing tracing. The tracing main loop is implemented here and callbacks are delivered to the EventConsumer interface.

Note that this class uses the wait() family of system calls to keep track of trace events. This API consumes process-global events, which means that there will be problems if other components in the same process deal with child processes, like:

extra events will be seen that libclues / the other component is not prepared for.
events that are expected by libclues can be lost to the other component.

For this reason it is simply not sensibly possible to create regular child process in parallel to tracing.

Definition at line 45 of file Engine.hxx.

Member Typedef Documentation

◆ EventMap

using clues::Engine::EventMap = std::map<cosmos::ProcessID, cosmos::ChildState>

protected

Definition at line 171 of file Engine.hxx.

◆ FormatFlags

using clues::Engine::FormatFlags = cosmos::BitMask<FormatFlag>

Definition at line 53 of file Engine.hxx.

◆ TraceeMap

using clues::Engine::TraceeMap = std::map<cosmos::ProcessID, TraceePtr>

protected

Definition at line 169 of file Engine.hxx.

Member Enumeration Documentation

◆ Decision

enum class clues::Engine::Decision

strongprotected

Different decisions what to do with ptrace events.

Enumerator
RETRY	retry processing the event.
DROP	ignore/drop the event.
STORE	store the event for later.
DONE	the event has been successfully processed.

Definition at line 174 of file Engine.hxx.

◆ FormatFlag

enum class clues::Engine::FormatFlag : uint64_t

strong

Enumerator
FD_INFO	print detailed file descriptor information

Definition at line 49 of file Engine.hxx.

                              : uint64_t {
                FD_INFO = 1, 
        };

Constructor & Destructor Documentation

◆ Engine()

clues::Engine::Engine ( EventConsumer & consumer )

inlineexplicit

Creates a new Engine that reports events to consumer.

Definition at line 58 of file Engine.hxx.

                                                 :
                        m_consumer{consumer} {
        }

◆ ~Engine()

clues::Engine::~Engine ( )

virtual

Tear down any tracees.

If tracees are still present then they will be detached from via stop(cosmos::signal::KILL).

Definition at line 18 of file Engine.cxx.

                {
        if (!m_tracees.empty()) {
                try {
                        stop(cosmos::signal::KILL);
                        trace();
                } catch (const std::exception &ex) {
                        LOG_WARN("Trying to stop remaining tracess in ~Engine():" << ex.what());
 
                        if (!m_tracees.empty()) {
                                LOG_ERROR("Failed to cleanup Engine");
                                std::abort();
                        }
                }
        }
 
        for (auto &pair: m_unknown_events) {
                LOG_WARN("Unknown event for PID " << cosmos::to_integral(pair.first) << " left unprocessed");
        }
}

Member Function Documentation

◆ addTracee() [1/2]

TraceePtr clues::Engine::addTracee	(	const cosmos::ProcessID	pid,
		const FollowChildren	follow_children,
		const AttachThreads	attach_threads,
		const cosmos::ProcessID	sibling = cosmos::ProcessID::INVALID )

Add the given pid as tracee.

For tracing unrelated processes the current process needs to have sufficient privileges. This is usually the case if you are root or if the target process has the same credentials as the current process.

The Linux Yama kernel security module can further restrict tracing of unrelated processes. Check the /proc/sys/kernel/yama/ptrace_scope file for more information.

If attaching fails then this call immediately throws an exception.

On success the target process will be interrupted to determine its current state. Any state can be encountered and the caller needs to be prepared for any kind of tracing event (signal, system call, process exit, ...) to occur as a result.

follow_children determines whether newly created child processes will automatically be attached.

See also: Tracee::attach().

attach_threads determines whether other threads of the target process should automatically be attached, too.

sibling´, if set, refers to an existing Tracee that belongs to the same process aspid`. The tracees will then share the same ProcessData.

Definition at line 38 of file Engine.cxx.

                                                                                   {
        TraceePtr sibling_ptr;
        if (auto it = m_tracees.find(sibling); it != m_tracees.end()) {
                sibling_ptr = it->second;
        }
        auto tracee = std::make_shared<ForeignTracee>(*this, m_consumer, sibling_ptr);
        tracee->configure(pid);
        tracee->attach(follow_children, attach_threads);
        m_tracees[pid] = tracee;
        return tracee;
}

◆ addTracee() [2/2]

TraceePtr clues::Engine::addTracee	(	const cosmos::StringVector &	cmdline,
		const FollowChildren	follow_children )

Create a new child process to be traced.

Use this function to create a new child process which will be traced from the very beginning. The first tracing event observed will typically be a system call entry.

follow_children determines whether newly created child processes will automatically be attached.

See also: Tracee::attach().

The library will perform an initial check whether the executable specified in cmdline exists and is executable. If this is not the case, then a RuntimeError is thrown. There can be other errors trying to execute the new process that cannot be caught before the new process is forked. To catch these situations, it is best to observe the tracee's system calls: If it exits before a successful initial execve() system call occurred, then a pre execution error happened.

Definition at line 51 of file Engine.cxx.

                                                                                                   {
        auto tracee = std::make_shared<ChildTracee>(*this, m_consumer);
        tracee->create(cmdline);
        tracee->attach(follow_children);
        m_tracees[tracee->pid()] = tracee;
        return tracee;
}

◆ checkCleanupTracee()

void clues::Engine::checkCleanupTracee ( TraceeMap::iterator it )

protected

Definition at line 59 of file Engine.cxx.

                                                    {
        auto &tracee = *it->second;
 
        if (tracee.state() == Tracee::State::DETACHED) {
                if (!tracee.isChildProcess()) {
                        m_tracees.erase(it);
                }
        } else if (tracee.state() == Tracee::State::DEAD) {
                tracee.doDetach();
                m_tracees.erase(it);
        }
}

◆ checkUnknownEvents()

void clues::Engine::checkUnknownEvents ( )

protected

Definition at line 72 of file Engine.cxx.

                                {
        if (m_newly_attached_pid == cosmos::ProcessID::INVALID)
                return;
 
        const auto new_pid = m_newly_attached_pid;
        m_newly_attached_pid = cosmos::ProcessID::INVALID;
 
        if (auto it = m_unknown_events.find(new_pid); it != m_unknown_events.end()) {
                if (handleEvent(it->second) != Decision::DONE) {
                        // this should not cause any special outcomes anymore
                        LOG_WARN("delayed handling of unknown event yielded unexpected decision");
                }
                m_unknown_events.erase(it);
        }
}

◆ checkUnknownTraceeEvent()

Engine::Decision clues::Engine::checkUnknownTraceeEvent ( const cosmos::ChildState & data )

protected

Check the given trace event if we can make sense of it.

If the function was able to adjust internal state for being able to properly handle data, then it returns true and a retry should be performed. Otherwise false is returned and the event should be discarded.

Definition at line 192 of file Engine.cxx.

                                                                           {
 
        if (data.trapped() && data.signal->isPtraceEventStop()) {
                const auto [_, event] = cosmos::ptrace::decode_event(*data.signal);
                if (event == cosmos::ptrace::Event::EXEC) {
                        /*
                         * This means execve() happened in a multi-threaded
                         * process, but we're not tracing the main thread,
                         * only the exec()'ing thread.
                         *
                         * The exec()'ing thread now has become the main
                         * thread, changing PID personality. Try to recover.
                         */
                        cosmos::Tracee ptrace{data.child.pid};
                        const auto former_pid = ptrace.getPIDEventMsg();
                        LOG_DEBUG("PID " << cosmos::to_integral(former_pid) << " issued execve(), but main thread is not traced. Trying to update records.");
                        if (tryUpdateTraceePID(former_pid, data.child.pid)) {
                                return Decision::RETRY;
                        }
 
                        return Decision::DROP;
                } else if (event == cosmos::ptrace::Event::STOP) {
                        /*
                         * this can actually happen when an auto-attached
                         * child tracee is created and scheduled before the
                         * creating parent has had a chance to reports its
                         * PTRACE_EVENT_CLONE & friend event.
                         *
                         * Without knowing the relation of parent/child it's
                         * plain confusing to forwarding this to clients of
                         * Engine. Store the event and forward it once we see
                         * the creation event.
                         */
                        LOG_DEBUG("PID " << cosmos::to_integral(data.child.pid)
                                        << " likely auto-attached tracee for which we didn't see the CLONE/[V]FORK event yet, storing event for later.");
                        return Decision::STORE;
                }
        }
 
        return Decision::DROP;
}

◆ formatFlags()

FormatFlags clues::Engine::formatFlags ( ) const

inline

Definition at line 154 of file Engine.hxx.

                                        {
                return m_format_flags;
        }

◆ handleAutoAttach()

void clues::Engine::handleAutoAttach	(	Tracee &	parent,
		const cosmos::ProcessID	pid,
		const cosmos::ptrace::Event	event,
		const SystemCall &	sc )

protected

Invoked by a Tracee once a new child process is auto-attached.

pid provides the process ID of the new child process and event describes the event that triggered the creation of the new child. sc refers to the system call that lead to the creation of the new child, providing additional details of child properties.

Definition at line 263 of file Engine.cxx.

                                                                     {
 
        LOG_DEBUG("auto-attach for " << cosmos::to_integral(pid));
 
        if (event != cosmos::ptrace::Event::VFORK_DONE) {
                auto tracee = std::make_shared<AutoAttachedTracee>(
                                *this,
                                m_consumer,
                                m_tracees[parent.pid()]);
 
                tracee->configure(pid, event, sc);
 
                auto [it, _] = m_tracees.insert({pid, tracee});
 
                EventConsumer::StatusFlags flags;
                if (parent.hasClonedThread()) {
                        flags.set(EventConsumer::StatusFlag::CLONED_THREAD);
                }
                m_consumer.newChildProcess(parent, *it->second, event, flags);
 
                checkCleanupTracee(it);
        } else {
                // if the pid is no longer found then it either already died
                // or it was detached from
                if (auto it = m_tracees.find(pid); it != m_tracees.end()) {
                        m_consumer.vforkComplete(parent, it->second);
                } else {
                        m_consumer.vforkComplete(parent, nullptr);
                }
        }
 
        /*
         * If we have any unknown events stored, we can now check whether they
         * have a matching object by now. Don't do this right away, because
         * `parent` is still busy processing its event. Only do this after
         * that is finished. This is the purpose of this flag.
         */
        m_newly_attached_pid = pid;
}

◆ handleEvent()

Engine::Decision clues::Engine::handleEvent ( const cosmos::ChildState & data )

protected

Definition at line 157 of file Engine.cxx.

                                                               {
        if (auto it = m_tracees.find(data.child.pid); it != m_tracees.end()) {
                Tracee &tracee = *it->second;
                try {
                        tracee.processEvent(data);
                } catch (const cosmos::ApiError &ex) {
                        auto pid = cosmos::to_integral(tracee.pid());
                        if (ex.errnum() == cosmos::Errno::SEARCH) {
                                /*
                                 * this can happen when the process was killed in the
                                 * meantime, or in a multi-threaded process when
                                 * another thread called execve() in parallel.
                                 *
                                 * we _should_ still receive an exit notification
                                 * about the tracee, and the consumer can then detect
                                 * that the system call was interrupted (actually if
                                 * this is a system call exit event, then it wasn't
                                 * interrupted, but we couldn't finish tracing it.
                                 * Kind of a small loophole).
                                 */
                                LOG_INFO("tracee " << pid << " disappeared");
                        } else {
                                // something more severe
                                LOG_ERROR("tracee " << pid << " handling process event failed: " << ex.what());
                        }
                }
 
                checkCleanupTracee(it);
                checkUnknownEvents();
                return Decision::DONE;
        } else {
                return checkUnknownTraceeEvent(data);
        }
}

◆ handleNoChildren()

void clues::Engine::handleNoChildren ( )

protected

Definition at line 88 of file Engine.cxx.

                              {
        for (auto it = m_tracees.begin(); it != m_tracees.end(); it++) {
                auto &tracee = it->second;
 
                if (tracee->flags()[Tracee::Flag::WAIT_FOR_EXITED]) {
                        /*
                         * This can be observed with the main thread when
                         * another thread (which isn't traced) calls execve().
                         *
                         * For this situation no EXITED wait() status is
                         * reported for the main thread, only PTHREAD_EXIT is
                         * seen. After that we can ECHLD with wait() and ESRCH
                         * with ptrace().
                         */
                        LOG_DEBUG("Tracee "
                                        << cosmos::to_integral(tracee->pid())
                                        << " likely disappeared because of execve() in another thread");
                } else {
                        LOG_WARN("Tracee " << cosmos::to_integral(tracee->pid())
                                        << " suddenly lost?!");
                }
 
                // actually we already seem to be detached, but this function
                // also takes care of this case and properly resets object
                // state
                tracee->detach();
 
                checkCleanupTracee(it);
        }
}

◆ handleSubstitution()

TraceePtr clues::Engine::handleSubstitution ( const cosmos::ProcessID old_pid )

protected

Invoked by a Tracee when multi-threaded execve() leads to substitution of a PID by another.

Definition at line 304 of file Engine.cxx.

                                                                  {
        /*
         * The following scenarios exist for multi-threaded processes:
         *
         * a) we are tracing all threads of the process. Some thread calls
         * execve(). We'll see all other threads exiting out of the blue. The
         * main thread's Tracee object will set the
         * WAIT_FOR_EXECVE_REPLACEMENT flag. Once the PID personality change
         * happens we'll recycle the main thread's Tracee object to be used
         * for further tracing. The reason for this is that the Tracee object
         * may be a ChildTracee with ownership of a SubProc that needs to live
         * on.
         *
         * b) we are only tracing a thread other than the main thread or the
         * execve() thread: it will just exit and tracing ends
         *
         * c) we are only tracing the execve() thread which is not the main
         * thread. Upon PID substitution we'll suddenly get a ptrace()
         * event for a PID we never attached to. Engine decodes the event in
         * `checkUnknownTraceeEvent()` and will update the key in `m_tracees`,
         * then feed the event to the Tracee object. In this case the only
         * available Tracee object will be kept.
         *
         * d) we are tracing only the main thread but another thread calls
         * execve(): the thread disappears and `wait()` suddenly fails
         * with ENOCHILD.
         *
         * What does strace do in these cases?
         *
         * - in case c) it sees the ptrace event for the changed PID, then
         *   detaches from it stating it is an unknown PID. Then tracing ends.
         * - in case d) it fails with ENOCHILD and tracing ends.
         *
         * Technically is is possible to deal with case c), which is complex
         * but managable. It makes sense to continue tracing in this case.
         *
         * In case d) it could be argued that is also makes sense to continue
         * tracing, since the main thread is traced but continues in another
         * context. Technically it is not possible to do this, though, because
         * we have no information at all about the execve() that is happening
         * until we lose the tracee. Thus in this case we try to detach cleanly.
         * Clients of libclues can identify the exit reason via
         * Tracee::flags() by looking for Flag::WAIT_FOR_EXECVE_REPLACEMENT,
         * which will still be set in this scenario.
         */
 
        auto it = m_tracees.find(old_pid);
 
        if (it == m_tracees.end()) {
                // this is likely case c), the `old_pid` was not traced by us.
                return nullptr;
        }
 
        auto &old_tracee = *it->second;
 
        try {
                old_tracee.detach();
        } catch (const cosmos::ApiError &err) {
                // it seems the kernel implicitly detaches at this point
                if (err.errnum() != cosmos::Errno::SEARCH) {
                        throw;
                }
        }
 
        auto ret = it->second;
 
        m_tracees.erase(it);
 
        /* The man page says at this stage we should forget about any other
         * treads of the process that still exist.
         * Is this really necessary? It also says that it is guaranteed that
         * only two threads will still exist now: the main and the execve()
         * thread. So forgetting about any other threads would only be
         * relevant for the non-execve() thread that still remains. We already
         * deal successfully with all the constellations that can occur, so I
         * don't think there's any explicit "forgetting" to be implemented
         * here.
         */
 
        return ret;
}

◆ setFormatFlags()

void clues::Engine::setFormatFlags ( const FormatFlags flags )

inline

Change formatting behaviour for system calls.

These flags influences the implementation of SystemCallItem::str(). See FormatFlag for details.

Definition at line 163 of file Engine.hxx.

                                                     {
                m_format_flags = flags;
        }

◆ stop()

void clues::Engine::stop ( const std::optional< cosmos::Signal > signal )

Stop tracing any active tracees.

If you want to stop a running trace then you can call this function to initiate detach from all active tracees. Each tracee will either be immediately be detached from, if its current state allows this, or it will be interrupted to detach from it during the next ptrace event.

If new child processes have been created for tracing then signal determines how they will be dealt with:

std::nullopt means that they will be waited for, without sending a signal. This can mean that it will take a long time before the child processes terminate and the trace() call can return.
Otherwise signal denotes the signal that will be sent to direct children to have them terminate in a timely fashion. cosmos::signal::KILL will be the safest way to tear down any remaining child processes.

After calling this function an active trace() invocation should be returning soon. Further trace events may be reported to the EventConsumer interface until the detachment process is complete.

Definition at line 249 of file Engine.cxx.

                                                        {
        for (auto it = m_tracees.begin(); it != m_tracees.end(); it++) {
                auto &tracee = *it->second;
                if (tracee.isChildProcess() && tracee.alive() && signal) {
                        cosmos::signal::send(tracee.pid(), *signal);
                }
                tracee.detach();
 
                if (!tracee.alive()) {
                        m_tracees.erase(it);
                }
        }
}

◆ trace()

void clues::Engine::trace ( )

Enter the tracing main loop and process tracing events.

At least one tracee must have been added via addTracee() for this call to do anything. The call will block and deliver tracing events to the given consumer interface until all of the tracees have exited or have been detached from.

Definition at line 119 of file Engine.cxx.

                   {
        cosmos::ChildState data;
 
        while (!m_tracees.empty()) {
                try {
                        data = *cosmos::proc::wait(cosmos::WaitFlags{
                                        cosmos::WaitFlag::WAIT_FOR_EXITED,
                                        cosmos::WaitFlag::WAIT_FOR_STOPPED});
                } catch (const cosmos::ApiError &ex) {
                        if (ex.errnum() == cosmos::Errno::NO_CHILD) {
                                handleNoChildren();
                                return;
                        }
 
                        throw;
                }
 
                while (true) {
                        if (const auto decision = handleEvent(data); decision == Decision::RETRY) {
                                // retry if we can process the event the next time.
                                continue;
                        } else if (decision == Decision::STORE) {
                                const auto res = m_unknown_events.insert(
                                                std::make_pair(data.child.pid, std::move(data)));
                                if (!res.second) {
                                        // we only expect one unknown event to appear per PID (PTRACE_EVENT_STOP)
                                        LOG_WARN("additional unknown trace event for PID " <<
                                                        cosmos::to_integral(data.child.pid));
                                }
                        } else if (decision == Decision::DROP) {
                                LOG_WARN("received unknown trace event " << format::event(data));
                        }
 
                        break;
                }
        }
}

◆ tryUpdateTraceePID()

bool clues::Engine::tryUpdateTraceePID	(	const cosmos::ProcessID	old_pid,
		const cosmos::ProcessID	new_pid )

protected

Definition at line 234 of file Engine.cxx.

                                                                                            {
        auto node = m_tracees.extract(old_pid);
        if (node.empty())
                return false;
        // don't change the Tracee object's PID just yet. This will be done
        // in Tracee::handleExecEvent()).
        //
        // At this stage we just want to be able to lookup the correct Tracee
        // within Engine for now.
        node.key() = new_pid;
 
        m_tracees.insert(std::move(node));
        return true;
}

Friends And Related Symbol Documentation

◆ Tracee

friend class Tracee

friend

Definition at line 46 of file Engine.hxx.

Member Data Documentation

◆ m_consumer

EventConsumer& clues::Engine::m_consumer

protected

Definition at line 223 of file Engine.hxx.

◆ m_format_flags

FormatFlags clues::Engine::m_format_flags

protected

Format settings for all tracees attached to this engine.

Definition at line 225 of file Engine.hxx.

◆ m_newly_attached_pid

cosmos::ProcessID clues::Engine::m_newly_attached_pid = cosmos::ProcessID::INVALID

protected

The PID of a newly auto-attached Tracee, if any.

Definition at line 222 of file Engine.hxx.

◆ m_tracees

TraceeMap clues::Engine::m_tracees

protected

Currently active tracees.

Definition at line 218 of file Engine.hxx.

◆ m_unknown_events

EventMap clues::Engine::m_unknown_events

protected

Unknown ptrace events stored for later processing.

Definition at line 220 of file Engine.hxx.

The documentation for this class was generated from the following files:

include/Engine.hxx
src/Engine.cxx

Public Types

Public Member Functions

Protected Types

Protected Member Functions

Protected Attributes

Friends

Detailed Description

Member Typedef Documentation

◆ EventMap

◆ FormatFlags

◆ TraceeMap

Member Enumeration Documentation

◆ Decision

◆ FormatFlag

Constructor & Destructor Documentation

◆ Engine()

◆ ~Engine()

Member Function Documentation

◆ addTracee() [1/2]

◆ addTracee() [2/2]

◆ checkCleanupTracee()

◆ checkUnknownEvents()

◆ checkUnknownTraceeEvent()

◆ formatFlags()

◆ handleAutoAttach()

◆ handleEvent()

◆ handleNoChildren()

◆ handleSubstitution()

◆ setFormatFlags()

◆ stop()

◆ trace()

◆ tryUpdateTraceePID()

Friends And Related Symbol Documentation

◆ Tracee

Member Data Documentation

◆ m_consumer

◆ m_format_flags

◆ m_newly_attached_pid

◆ m_tracees

◆ m_unknown_events