From 1125313fda417db9382f5fae62a41a653278f80b Mon Sep 17 00:00:00 2001 From: Jorge Matricali Date: Thu, 25 Jul 2024 20:48:45 -0300 Subject: [PATCH] Update doc blocks --- src/bruteforce_ssh.c | 49 ++++++++++++++++++++++- src/bruteforce_ssh.h | 41 ++++++++++++++++++- src/compat.h | 38 +++++++++++++++++- src/credentials.c | 28 +++++++++++-- src/credentials.h | 30 ++++++++++---- src/detection.c | 54 ++++++++++++++++++++++++- src/detection.h | 47 +++++++++++++++++++++- src/iprange.c | 54 +++++++++++++++---------- src/iprange.h | 50 ++++++++++++++--------- src/log.c | 41 ++++++++++++++++++- src/log.h | 85 +++++++++++++++++++++++++++++++++++---- src/progressbar.c | 29 +++++++++----- src/progressbar.h | 18 ++++++++- src/str.c | 95 ++++++++++++++------------------------------ src/str.h | 29 ++++++++++++-- src/target.c | 48 +++++++++++++++++----- src/target.h | 63 ++++++++++++++++++++++++++++- 17 files changed, 641 insertions(+), 158 deletions(-) diff --git a/src/bruteforce_ssh.c b/src/bruteforce_ssh.c index a638aa8..304fe8e 100644 --- a/src/bruteforce_ssh.c +++ b/src/bruteforce_ssh.c @@ -1,5 +1,5 @@ /* -Copyright (c) 2014-2018 Jorge Matricali +Copyright (c) 2014-2024 Jorge Matricali Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal @@ -33,6 +33,21 @@ SOFTWARE. static pthread_mutex_t bflock = PTHREAD_MUTEX_INITIALIZER; +/** + * Attempt to brute-force SSH login using the provided credentials. + * + * This function tries to log in to the SSH server using the specified hostname, + * port, username, and password. It performs the brute-force attempt and handles + * any related errors. + * + * @param context The context containing options and configurations for brute-force. + * @param hostname The hostname of the SSH server. + * @param port The port of the SSH server. + * @param username The username to use for the login attempt. + * @param password The password to use for the login attempt. + * + * @return 0 on success, non-zero on failure. + */ int bruteforce_ssh_login(btkg_context_t *context, const char *hostname, uint16_t port, const char *username, const char *password) @@ -116,6 +131,20 @@ int bruteforce_ssh_login(btkg_context_t *context, const char *hostname, return -1; } +/** + * Try to log in to an SSH server with the specified credentials. + * + * This function tries a single login attempt using the provided credentials and + * returns the result of the attempt. + * + * @param context The context containing options and configurations for brute-force. + * @param hostname The hostname of the SSH server. + * @param port The port of the SSH server. + * @param username The username to use for the login attempt. + * @param password The password to use for the login attempt. + * + * @return 0 on success, non-zero on failure. + */ int bruteforce_ssh_try_login(btkg_context_t *context, const char *hostname, const uint16_t port, const char *username, const char *password) @@ -143,6 +172,16 @@ int bruteforce_ssh_try_login(btkg_context_t *context, const char *hostname, return ret; } +/** + * Worker function for brute-force SSH login attempts. + * + * This function is executed by each worker thread to perform brute-force SSH login attempts + * on the specified targets using the provided credentials. + * + * @param ptr Pointer to the context containing targets, credentials, and options. + * + * @return NULL when the worker completes its task. + */ static void *btkg_bruteforce_worker(void *ptr) { btkg_context_t *context = (btkg_context_t *)ptr; @@ -198,6 +237,14 @@ static void *btkg_bruteforce_worker(void *ptr) return NULL; } +/** + * Start the brute-force SSH login process. + * + * This function initializes and starts the brute-force process, including setting + * up necessary threads and handling the brute-force attack. + * + * @param context The context containing options and configurations for brute-force. + */ void btkg_bruteforce_start(btkg_context_t *context) { btkg_options_t *options = &context->options; diff --git a/src/bruteforce_ssh.h b/src/bruteforce_ssh.h index 49a72c5..5c26abc 100644 --- a/src/bruteforce_ssh.h +++ b/src/bruteforce_ssh.h @@ -1,5 +1,5 @@ /* -Copyright (c) 2014-2018 Jorge Matricali +Copyright (c) 2014-2024 Jorge Matricali Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal @@ -27,14 +27,51 @@ SOFTWARE. #include "cbrutekrag.h" +/** + * Attempt to brute-force SSH login using the provided credentials. + * + * This function tries to log in to the SSH server using the specified hostname, + * port, username, and password. It performs the brute-force attempt and handles + * any related errors. + * + * @param context The context containing options and configurations for brute-force. + * @param hostname The hostname of the SSH server. + * @param port The port of the SSH server. + * @param username The username to use for the login attempt. + * @param password The password to use for the login attempt. + * + * @return 0 on success, non-zero on failure. + */ int bruteforce_ssh_login(btkg_context_t *context, const char *hostname, uint16_t port, const char *username, const char *password); +/** + * Try to log in to an SSH server with the specified credentials. + * + * This function tries a single login attempt using the provided credentials and + * returns the result of the attempt. + * + * @param context The context containing options and configurations for brute-force. + * @param hostname The hostname of the SSH server. + * @param port The port of the SSH server. + * @param username The username to use for the login attempt. + * @param password The password to use for the login attempt. + * + * @return 0 on success, non-zero on failure. + */ int bruteforce_ssh_try_login(btkg_context_t *context, const char *hostname, const uint16_t port, const char *username, const char *password); +/** + * Start the brute-force SSH login process. + * + * This function initializes and starts the brute-force process, including setting + * up necessary threads and handling the brute-force attack. + * + * @param context The context containing options and configurations for brute-force. + */ void btkg_bruteforce_start(btkg_context_t *context); -#endif /* BRUTEFORCE_SSH_H */ +#endif // BRUTEFORCE_SSH_H diff --git a/src/compat.h b/src/compat.h index 14853fd..d72d735 100644 --- a/src/compat.h +++ b/src/compat.h @@ -1,5 +1,5 @@ /* -Copyright (c) 2014-2018 Jorge Matricali +Copyright (c) 2014-2024 Jorge Matricali Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal @@ -20,13 +20,49 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. */ +/** + * @file compat.h + * @brief Compatibility layer for systems lacking certain standard library functions. + * + * This header provides declarations for functions that may not be available + * on all platforms. If the functions are not available, they are implemented + * elsewhere in the codebase to ensure compatibility across different systems. + */ + #ifndef COMPAT_H #define COMPAT_H +#include + +/** + * @brief Read a delimited record from a stream. + * + * This function reads a line from the specified stream, delimited by the + * specified character. It is intended for platforms that do not support + * the `getdelim` function. + * + * @param buf Pointer to the buffer where the line should be stored. + * @param bufsiz Pointer to the size of the buffer. + * @param delimiter The character that delimits the record. + * @param fp The file stream to read from. + * @return The number of characters read, or -1 on error or end of file. + */ #if !HAVE_GETDELIM ssize_t getdelim(char **buf, size_t *bufsiz, int delimiter, FILE *fp); #endif +/** + * @brief Read an entire line from a stream. + * + * This function reads a line from the specified stream, stopping at the end + * of the line or the end of the file. It is intended for platforms that do not + * support the `getline` function. + * + * @param buf Pointer to the buffer where the line should be stored. + * @param bufsiz Pointer to the size of the buffer. + * @param fp The file stream to read from. + * @return The number of characters read, or -1 on error or end of file. + */ #if !HAVE_GETLINE ssize_t getline(char **buf, size_t *bufsiz, FILE *fp); #endif diff --git a/src/credentials.c b/src/credentials.c index 3537ce9..d30f012 100644 --- a/src/credentials.c +++ b/src/credentials.c @@ -30,6 +30,14 @@ SOFTWARE. char *g_blankpass_placeholder = "$BLANKPASS"; +/** + * @brief Parses a line into a btkg_credentials_t structure. + * + * @param line The line to parse. + * @param dst Pointer to the btkg_credentials_t structure to fill with parsed data. + * + * @return 0 on success, non-zero on failure. + */ int btkg_credentials_parse(char *line, btkg_credentials_t *dst) { dst->username[0] = '\0'; @@ -51,7 +59,9 @@ int btkg_credentials_parse(char *line, btkg_credentials_t *dst) } /** - * Initialize btkg_credentials_list_t + * @brief Initializes a btkg_credentials_list_t structure. + * + * @param credentials Pointer to the btkg_credentials_list_t structure to initialize. */ void btkg_credentials_list_init(btkg_credentials_list_t *credentials) { @@ -60,8 +70,10 @@ void btkg_credentials_list_init(btkg_credentials_list_t *credentials) } /** - * Loads credentials from a given file and append them into the given - * btkg_credentials_list_t + * @brief Loads credentials from a given file and appends them into the given btkg_credentials_list_t. + * + * @param credentials_list Pointer to the btkg_credentials_list_t structure to append the loaded credentials to. + * @param filename The name of the file to load the credentials from. */ void btkg_credentials_list_load(btkg_credentials_list_t *credentials_list, char *filename) @@ -96,7 +108,10 @@ void btkg_credentials_list_load(btkg_credentials_list_t *credentials_list, } /** - * Append btkg_credentials_t into given btkg_credentials_list_t + * @brief Appends a btkg_credentials_t structure into a given btkg_credentials_list_t. + * + * @param credentials_list Pointer to the btkg_credentials_list_t structure to append the credentials to. + * @param new The btkg_credentials_t structure to append. */ void btkg_credentials_list_append(btkg_credentials_list_t *credentials_list, btkg_credentials_t new) @@ -117,6 +132,11 @@ void btkg_credentials_list_append(btkg_credentials_list_t *credentials_list, credentials_list->credentials = credentials; } +/** + * @brief Frees the memory allocated for a btkg_credentials_list_t structure. + * + * @param credentials_list Pointer to the btkg_credentials_list_t structure to free. + */ void btkg_credentials_list_destroy(btkg_credentials_list_t *credentials_list) { free(credentials_list->credentials); diff --git a/src/credentials.h b/src/credentials.h index ba4165e..b2b6eda 100644 --- a/src/credentials.h +++ b/src/credentials.h @@ -1,5 +1,5 @@ /* -Copyright (c) 2014-2018 Jorge Matricali +Copyright (c) 2014-2024 Jorge Matricali Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal @@ -43,31 +43,45 @@ typedef struct { } btkg_credentials_list_t; /** - * Initialize btkg_credentials_list_t + * @brief Initializes a btkg_credentials_list_t structure. + * + * @param credentials Pointer to the btkg_credentials_list_t structure to initialize. */ void btkg_credentials_list_init(btkg_credentials_list_t *credentials); /** - * Parse line into btkg_credentials_t structure + * @brief Parses a line into a btkg_credentials_t structure. + * + * @param line The line to parse. + * @param dst Pointer to the btkg_credentials_t structure to fill with parsed data. + * + * @return 0 on success, non-zero on failure. */ int btkg_credentials_parse(char *line, btkg_credentials_t *dst); /** - * Loads credentials from a given file and append them into the given - * btkg_credentials_list_t + * @brief Loads credentials from a given file and appends them into the given btkg_credentials_list_t. + * + * @param credentials_list Pointer to the btkg_credentials_list_t structure to append the loaded credentials to. + * @param filename The name of the file to load the credentials from. */ void btkg_credentials_list_load(btkg_credentials_list_t *credentials_list, char *filename); /** - * Append btkg_credentials_t into given btkg_credentials_list_t + * @brief Appends a btkg_credentials_t structure into a given btkg_credentials_list_t. + * + * @param credentials_list Pointer to the btkg_credentials_list_t structure to append the credentials to. + * @param new The btkg_credentials_t structure to append. */ void btkg_credentials_list_append(btkg_credentials_list_t *credentials_list, btkg_credentials_t new); /** - * Free btkg_credentials_list_t + * @brief Frees the memory allocated for a btkg_credentials_list_t structure. + * + * @param credentials_list Pointer to the btkg_credentials_list_t structure to free. */ void btkg_credentials_list_destroy(btkg_credentials_list_t *credentials_list); -#endif /* __BTKG_CREDENTIALS_H */ +#endif // __BTKG_CREDENTIALS_H diff --git a/src/detection.c b/src/detection.c index cf25b7b..8c2eda9 100644 --- a/src/detection.c +++ b/src/detection.c @@ -1,5 +1,5 @@ /* -Copyright (c) 2014-2018 Jorge Matricali +Copyright (c) 2014-2024 Jorge Matricali Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal @@ -56,6 +56,18 @@ size_t scan_counter = 0; btkg_target_list_t filtered; static pthread_mutex_t mutex = PTHREAD_MUTEX_INITIALIZER; +/** + * Detect login methods supported by the SSH server. + * + * This function tries to detect supported authentication methods on the SSH + * server by checking if it allows user authentication with no credentials. + * + * @param session The SSH session to check. + * @param hostname The hostname of the SSH server. + * @param port The port of the SSH server. + * + * @return 0 if password authentication is supported, -1 otherwise. + */ int detection_login_methods(ssh_session session, const char *hostname, int port) { int rc = 0; @@ -87,6 +99,23 @@ int detection_login_methods(ssh_session session, const char *hostname, int port) return -1; } +/** + * Detect if the SSH service is running and if it supports + * password authentication. + * + * This function connects to an SSH server and checks its banner and + * authentication methods to determine if it's a valid SSH service and if + * it supports password authentication. + * + * @param ctx The context containing options for detection. + * @param hostname The hostname of the SSH server. + * @param port The port of the SSH server. + * @param tm The timeout for the SSH connection. + * + * @return 0 if the server is a valid SSH server with password authentication, + * 1 if there is a connection error, -1 if the server does not meet + * the criteria. + */ int detection_detect_ssh(btkg_context_t *context, const char *hostname, uint16_t port, long tm) { @@ -202,6 +231,17 @@ int detection_detect_ssh(btkg_context_t *context, const char *hostname, return 0; } +/** + * Thread function to process detection for each target. + * + * This function processes targets from the target list, detects SSH services + * and their authentication methods, and updates the filtered target list. + * + * @param ptr A pointer to a btkg_detection_args_t structure containing the + * context and target list. + * + * @return NULL + */ void *detection_process(void *ptr) { btkg_detection_args_t *args = (btkg_detection_args_t *)ptr; @@ -251,6 +291,18 @@ void *detection_process(void *ptr) return NULL; } +/** + * Start the detection process with multiple threads. + * + * This function initializes and starts multiple threads to process the target + * list and detect SSH services. It waits for all threads to complete before + * updating the target list with the results. + * + * @param context The context containing options for the detection. + * @param source The source target list to process. + * @param targets The target list to store the results. + * @param max_threads The maximum number of threads to use. + */ void detection_start(btkg_context_t *context, btkg_target_list_t *source, btkg_target_list_t *targets, size_t max_threads) { diff --git a/src/detection.h b/src/detection.h index dc67246..a023a54 100644 --- a/src/detection.h +++ b/src/detection.h @@ -1,5 +1,5 @@ /* -Copyright (c) 2014-2018 Jorge Matricali +Copyright (c) 2014-2024 Jorge Matricali Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal @@ -27,17 +27,60 @@ SOFTWARE. #include "target.h" +/** + * Structure to hold the arguments for detection threads. + */ typedef struct { btkg_context_t *context; btkg_target_list_t *target_list; } btkg_detection_args_t; +/** + * Detect if the SSH service is running and if it supports + * password authentication. + * + * This function connects to an SSH server and checks its banner and + * authentication methods to determine if it's a valid SSH service and if + * it supports password authentication. + * + * @param ctx The context containing options for detection. + * @param hostname The hostname of the SSH server. + * @param port The port of the SSH server. + * @param tm The timeout for the SSH connection. + * + * @return 0 if the server is a valid SSH server with password authentication, + * 1 if there is a connection error, -1 if the server does not meet + * the criteria. + */ int detection_detect_ssh(btkg_context_t *ctx, const char *hostname, uint16_t port, long tm); +/** + * Thread function to process detection for each target. + * + * This function processes targets from the target list, detects SSH services + * and their authentication methods, and updates the filtered target list. + * + * @param ptr A pointer to a btkg_detection_args_t structure containing the + * context and target list. + * + * @return NULL + */ void *detection_process(void *ptr); +/** + * Start the detection process with multiple threads. + * + * This function initializes and starts multiple threads to process the target + * list and detect SSH services. It waits for all threads to complete before + * updating the target list with the results. + * + * @param context The context containing options for the detection. + * @param source The source target list to process. + * @param target The target list to store the results. + * @param max_threads The maximum number of threads to use. + */ void detection_start(btkg_context_t *context, btkg_target_list_t *source, btkg_target_list_t *target, size_t max_threads); -#endif /* DETECTION_H */ +#endif // DETECTION_H diff --git a/src/iprange.c b/src/iprange.c index 64f840a..51cce4a 100644 --- a/src/iprange.c +++ b/src/iprange.c @@ -1,5 +1,5 @@ /* - * Copyright (C) 2018 Jorge Matricali + * Copyright (C) 2018-2024 Jorge Matricali * * This program is free software: you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by @@ -31,9 +31,13 @@ #include "iprange.h" /** - * Convert an A.B.C.D address into a 32-bit host-order value - * @param ipstr - * @return + * @brief Convert an IPv4 address in string format to a 32-bit host-order value. + * + * @param ipstr The IPv4 address in string format (e.g., "192.168.1.1"). + * + * @return The 32-bit host-order value of the IPv4 address. + * + * @note Exits the program with an error message if the address is invalid. */ in_addr_t a_to_hl(const char *ipstr) { @@ -48,13 +52,15 @@ in_addr_t a_to_hl(const char *ipstr) exit(1); } - return (ntohl(in.s_addr)); + return (in_addr_t)ntohl(in.s_addr); } /** - * Compute netmask address given prefix - * @param prefix - * @return + * @brief Compute the netmask address given a prefix length. + * + * @param prefix The prefix length (0 to 32). + * + * @return The netmask address as a 32-bit integer. */ in_addr_t netmask(int prefix) { @@ -66,10 +72,12 @@ in_addr_t netmask(int prefix) } /** - * Compute network address given address and prefix - * @param addr - * @param prefix - * @return + * @brief Compute the network address given an IP address and a prefix length. + * + * @param addr The IP address as a 32-bit integer. + * @param prefix The prefix length (0 to 32). + * + * @return The network address as a 32-bit integer. */ in_addr_t network(in_addr_t addr, int prefix) { @@ -77,10 +85,12 @@ in_addr_t network(in_addr_t addr, int prefix) } /** - * Compute broadcast address given address and prefix - * @param addr - * @param prefix - * @return + * @brief Compute the broadcast address given an IP address and a prefix length. + * + * @param addr The IP address as a 32-bit integer. + * @param prefix The prefix length (0 to 32). + * + * @return The broadcast address as a 32-bit integer. */ in_addr_t broadcast(in_addr_t addr, int prefix) { @@ -88,10 +98,14 @@ in_addr_t broadcast(in_addr_t addr, int prefix) } /** - * Convert a network address char string into a host-order network - * address and an integer prefix value - * @param ipstr - * @return + * @brief Convert a network address in string format into a host-order network address + * and an integer prefix value. + * + * @param ipstr The network address in string format (e.g., "192.168.1.0/24"). + * + * @return A network_addr_t structure containing the network address and prefix. + * + * @note Exits the program with an error message if the address or prefix is invalid. */ network_addr_t str_to_netaddr(const char *ipstr) { diff --git a/src/iprange.h b/src/iprange.h index 7c0d55c..94f5d7e 100644 --- a/src/iprange.h +++ b/src/iprange.h @@ -33,40 +33,54 @@ typedef struct network_addr { } network_addr_t; /** - * Convert an A.B.C.D address into a 32-bit host-order value - * @param ipstr - * @return + * @brief Convert an IPv4 address in string format to a 32-bit host-order value. + * + * @param ipstr The IPv4 address in string format (e.g., "192.168.1.1"). + * + * @return The 32-bit host-order value of the IPv4 address. + * + * @note Exits the program with an error message if the address is invalid. */ in_addr_t a_to_hl(const char *ipstr); /** - * Compute netmask address given prefix - * @param prefix - * @return + * @brief Compute the netmask address given a prefix length. + * + * @param prefix The prefix length (0 to 32). + * + * @return The netmask address as a 32-bit integer. */ in_addr_t netmask(int prefix); /** - * Compute network address given address and prefix - * @param addr - * @param prefix - * @return + * @brief Compute the network address given an IP address and a prefix length. + * + * @param addr The IP address as a 32-bit integer. + * @param prefix The prefix length (0 to 32). + * + * @return The network address as a 32-bit integer. */ in_addr_t network(in_addr_t addr, int prefix); /** - * Compute broadcast address given address and prefix - * @param addr - * @param prefix - * @return + * @brief Compute the broadcast address given an IP address and a prefix length. + * + * @param addr The IP address as a 32-bit integer. + * @param prefix The prefix length (0 to 32). + * + * @return The broadcast address as a 32-bit integer. */ in_addr_t broadcast(in_addr_t addr, int prefix); /** - * Convert a network address char string into a host-order network - * address and an integer prefix value - * @param ipstr - * @return + * @brief Convert a network address in string format into a host-order network address + * and an integer prefix value. + * + * @param ipstr The network address in string format (e.g., "192.168.1.0/24"). + * + * @return A network_addr_t structure containing the network address and prefix. + * + * @note Exits the program with an error message if the address or prefix is invalid. */ network_addr_t str_to_netaddr(const char *ipstr); diff --git a/src/log.c b/src/log.c index 4d944b8..c81ee52 100644 --- a/src/log.c +++ b/src/log.c @@ -1,5 +1,5 @@ /* -Copyright (c) 2014-2018 Jorge Matricali +Copyright (c) 2014-2024 Jorge Matricali Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal @@ -29,11 +29,19 @@ SOFTWARE. #include "log.h" #include "str.h" /* btkg_str_replace_placeholder */ +/** Global verbosity level. */ extern int g_verbose; + +/** Global output format string. */ extern char *g_output_format; #define TIMESTAMP_BUFFER_SIZE 20 +/** + * @brief Get the current timestamp in the format YYYY/MM/DD HH:MM:SS. + * + * @return A pointer to a static buffer containing the timestamp. + */ static inline const char *get_current_timestamp(void) { time_t t = time(NULL); @@ -46,6 +54,19 @@ static inline const char *get_current_timestamp(void) return buffer; } +/** + * @brief Print formatted output to a specified stream with optional logging + * information such as file and line number. + * + * @param level The logging level of the message (e.g., LOG_DEBUG). + * @param file The source file from which the log is coming. + * @param line The line number in the source file. + * @param head A prefix string to be printed before the log message. + * @param tail A suffix string to be printed after the log message. + * @param stream The output stream (e.g., stdout or stderr). + * @param format The format string for the log message. + * @param ... Additional arguments for the format string. + */ void print_output(int level, const char *file, int line, const char *head, const char *tail, FILE *stream, const char *format, ...) { @@ -69,6 +90,13 @@ void print_output(int level, const char *file, int line, const char *head, fflush(stream); } +/** + * @brief Print formatted output to a specified stream with the current timestamp. + * + * @param stream The output stream (e.g., stdout or stderr). + * @param format The format string for the log message. + * @param ... Additional arguments for the format string. + */ void log_output(FILE *stream, const char *format, ...) { va_list arg; @@ -81,6 +109,17 @@ void log_output(FILE *stream, const char *format, ...) fflush(stream); } +/** + * @brief Log a successful login attempt with detailed information such as + * hostname, port, username, and password, formatted according to + * a global output format string. + * + * @param stream The output stream (e.g., stdout or stderr). + * @param hostname The hostname or IP address where the login was successful. + * @param port The port number used in the login attempt. + * @param username The username used in the login attempt. + * @param password The password used in the login attempt. + */ void btkg_log_successfull_login(FILE *stream, const char *hostname, int port, const char *username, const char *password) { diff --git a/src/log.h b/src/log.h index 9250f52..927bbe4 100644 --- a/src/log.h +++ b/src/log.h @@ -1,5 +1,5 @@ /* -Copyright (c) 2014-2018 Jorge Matricali +Copyright (c) 2014-2024 Jorge Matricali Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal @@ -23,33 +23,102 @@ SOFTWARE. #ifndef LOGGER_H #define LOGGER_H +/** + * @brief Logging levels. + */ enum { - LOG_TRACE, - LOG_DEBUG, - LOG_INFO, - LOG_WARN, - LOG_ERROR, - LOG_FATAL, + LOG_TRACE, /**< Trace level for detailed debugging. */ + LOG_DEBUG, /**< Debug level for general debugging information. */ + LOG_INFO, /**< Info level for informational messages. */ + LOG_WARN, /**< Warn level for warnings and potential issues. */ + LOG_ERROR, /**< Error level for error messages. */ + LOG_FATAL /**< Fatal level for critical errors that may cause termination. */ }; +/** + * @brief Log an error message with red color and file/line information. + * + * This macro calls `print_output` with the LOG_ERROR level, red color for + * the message, and includes file and line information. + * + * @param ... Format string and arguments for the error message. + */ #define log_error(...) \ print_output(LOG_ERROR, __FILE__, __LINE__, "\033[91m", "\033[0m", \ stderr, __VA_ARGS__) + +/** + * @brief Log a warning message without color and with file/line information. + * + * This macro calls `print_output` with the LOG_WARN level and includes file + * and line information. + * + * @param ... Format string and arguments for the warning message. + */ #define log_warn(...) \ print_output(LOG_WARN, __FILE__, __LINE__, "", "", stderr, __VA_ARGS__) +/** + * @brief Log a debug message with gray color and file/line information. + * + * This macro calls `print_output` with the LOG_DEBUG level, gray color for + * the message, and includes file and line information. + * + * @param ... Format string and arguments for the debug message. + */ #define log_debug(...) \ print_output(LOG_DEBUG, __FILE__, __LINE__, "\033[37m", "\033[0m", \ stderr, __VA_ARGS__) + +/** + * @brief Log an informational message without color and with no file/line + * information. + * + * This macro calls `print_output` with the LOG_INFO level and writes to + * stdout. + * + * @param ... Format string and arguments for the informational message. + */ #define log_info(...) \ print_output(LOG_INFO, __FILE__, __LINE__, "", "", stdout, __VA_ARGS__) +/** + * @brief Print a formatted output message to a specified stream with optional + * logging information such as file and line number. + * + * @param level The logging level of the message (e.g., LOG_DEBUG). + * @param file The source file from which the log is coming. + * @param line The line number in the source file. + * @param head A prefix string to be printed before the log message. + * @param tail A suffix string to be printed after the log message. + * @param stream The output stream (e.g., stdout or stderr). + * @param format The format string for the log message. + * @param ... Additional arguments for the format string. + */ void print_output(int level, const char *file, int line, const char *head, const char *tail, FILE *stream, const char *format, ...); +/** + * @brief Print a formatted output message with the current timestamp to a + * specified stream. + * + * @param stream The output stream (e.g., stdout or stderr). + * @param format The format string for the log message. + * @param ... Additional arguments for the format string. + */ void log_output(FILE *stream, const char *format, ...); +/** + * @brief Log a successful login attempt with details formatted according to + * a global output format string. + * + * @param stream The output stream (e.g., stdout or stderr). + * @param hostname The hostname or IP address where the login was successful. + * @param port The port number used in the login attempt. + * @param username The username used in the login attempt. + * @param password The password used in the login attempt. + */ void btkg_log_successfull_login(FILE *stream, const char *hostname, int port, const char *username, const char *password); -#endif /* LOGGER_H */ +#endif // LOGGER_H diff --git a/src/progressbar.c b/src/progressbar.c index 0304cd6..0e06fda 100644 --- a/src/progressbar.c +++ b/src/progressbar.c @@ -1,5 +1,5 @@ /* -Copyright (c) 2014-2018 Jorge Matricali +Copyright (c) 2014-2024 Jorge Matricali Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal @@ -33,8 +33,12 @@ SOFTWARE. #include /** - * Get the terminal width - * @return The width of the terminal + * Get the terminal width. + * + * This function retrieves the width of the terminal in columns. If the + * width cannot be determined, a default value of 80 columns is used. + * + * @return The width of the terminal in columns. */ static size_t get_terminal_width(void) { @@ -44,7 +48,8 @@ static size_t get_terminal_width(void) CONSOLE_SCREEN_BUFFER_INFO csbi; if (GetConsoleScreenBufferInfo(GetStdHandle(STD_OUTPUT_HANDLE), &csbi)) { - max_cols = csbi.srWindow.Right - csbi.srWindow.Left + 1; + max_cols = + (size_t)(csbi.srWindow.Right - csbi.srWindow.Left + 1); } #else struct winsize w; @@ -57,14 +62,18 @@ static size_t get_terminal_width(void) } /** - * Render progress bar like this: + * Render a progress bar to the terminal. + * + * This function displays a progress bar with a filled and empty section + * to represent progress, as well as a percentage and optional suffix. + * The bar is rendered to fit within the width of the terminal. + * * |███░░░░░░░░░░░░░░░░░░░░░| 14.51% [37] 192.168.100.37 root root * - * @author Jorge Matricali - * @param count Current iteration - * @param total Total iterations - * @param suffix String suffix - * @param bar_len Bar length + * @param count The current iteration count. + * @param total The total number of iterations. + * @param suffix A string suffix to append after the progress bar. + * @param bar_len The length of the progress bar in characters. */ void progressbar_render(size_t count, size_t total, const char *suffix, size_t bar_len) diff --git a/src/progressbar.h b/src/progressbar.h index b536c92..dce7517 100644 --- a/src/progressbar.h +++ b/src/progressbar.h @@ -1,5 +1,5 @@ /* -Copyright (c) 2014-2018 Jorge Matricali +Copyright (c) 2014-2024 Jorge Matricali Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal @@ -23,7 +23,21 @@ SOFTWARE. #ifndef PROGRESSBAR_H #define PROGRESSBAR_H +/** + * Render a progress bar to the terminal. + * + * This function displays a progress bar with a filled and empty section + * to represent progress, as well as a percentage and optional suffix. + * The bar is rendered to fit within the width of the terminal. + * + * |███░░░░░░░░░░░░░░░░░░░░░| 14.51% [37] 192.168.100.37 root root + * + * @param count The current iteration count. + * @param total The total number of iterations. + * @param suffix A string suffix to append after the progress bar. + * @param bar_len The length of the progress bar in characters. + */ void progressbar_render(size_t count, size_t total, char *suffix, size_t bar_len); -#endif /* PROGRESSBAR_H */ +#endif // PROGRESSBAR_H diff --git a/src/str.c b/src/str.c index 9484a00..a390e5f 100644 --- a/src/str.c +++ b/src/str.c @@ -42,67 +42,16 @@ void btkg_str_copy(char *dst, const char *src, size_t dst_size) } } -char **str_split(char *a_str, const char a_delim) -{ - char **result = 0; - size_t count = 0; - char *tmp = a_str; - char *last_comma = 0; - char delim[2]; - delim[0] = a_delim; - delim[1] = 0; - - /* Count how many elements will be extracted. */ - while (*tmp) { - if (a_delim == *tmp) { - count++; - last_comma = tmp; - } - tmp++; - } - - /* Add space for trailing token. */ - count += last_comma < (a_str + strlen(a_str) - 1); - - /* Add space for terminating null string so caller - knows where the list of returned strings ends. */ - count++; - - result = malloc(sizeof(char *) * count); - - if (result) { - size_t idx = 0; - char *token = strtok(a_str, delim); - - while (token) { - assert(idx < count); - *(result + idx++) = strdup(token); - token = strtok(0, delim); - } - assert(idx == count - 1); - *(result + idx) = 0; - } - - return result; -} - -// You must free the result if result is non-NULL. -const char *str_repeat(char *str, size_t times) -{ - if (times < 1) - return NULL; - char *ret = malloc(sizeof(str) * times + 1); - if (ret == NULL) - return NULL; - strcpy(ret, str); - while (--times > 0) { - strcat(ret, str); - } - return ret; -} - -// You must free the result if result is non-NULL. -char *str_replace(char *orig, char *rep, char *with) +/** + * @brief Replaces all occurrences of a substring within a string with another substring. + * + * @param orig The original string. + * @param rep The substring to replace. + * @param with The replacement substring. + * + * @return A new string with the replacements. Should be freed by the caller. + */ +char *btkg_str_replace(const char *orig, const char *rep, const char *with) { char *result; char *ins; @@ -123,15 +72,16 @@ char *str_replace(char *orig, char *rep, char *with) len_with = strlen(with); // count the number of replacements needed - ins = orig; + ins = (char *)orig; for (count = 0; (tmp = strstr(ins, rep)); ++count) { ins = tmp + len_rep; } tmp = result = malloc(strlen(orig) + (len_with - len_rep) * count + 1); - - if (!result) + if (!result) { + perror("malloc"); return NULL; + } // first time through the loop, all the variable are set correctly // from here on, @@ -149,11 +99,19 @@ char *str_replace(char *orig, char *rep, char *with) return result; } +/** + * @brief Replaces placeholders in a string with specified values. + * + * @param input The input string containing placeholders. + * @param search The placeholder to search for. + * @param replace The string to replace the placeholder with. + * + * @return A new string with placeholders replaced. Should be freed by the caller. + */ char *btkg_str_replace_placeholder(char *input, const char *search, const char *replace) { - char *tmp = NULL; - tmp = str_replace(input, (char *)search, (char *)replace); + char *tmp = btkg_str_replace(input, search, replace); if (tmp) { if (input) free(input); @@ -162,6 +120,11 @@ char *btkg_str_replace_placeholder(char *input, const char *search, return input; } +/** + * @brief Replaces escape sequences in a string with their corresponding characters. + * + * @param str The input string containing escape sequences. + */ void btkg_str_replace_escape_sequences(char *str) { char *read = str; diff --git a/src/str.h b/src/str.h index 9394d27..299a563 100644 --- a/src/str.h +++ b/src/str.h @@ -34,11 +34,34 @@ SOFTWARE. */ void btkg_str_copy(char *dst, const char *src, size_t dst_size); -char **str_split(char *a_str, const char a_delim); -const char *str_repeat(char *str, size_t times); -char *str_replace(char *orig, char *rep, char *with); +/** + * @brief Replaces all occurrences of a substring within a string with another substring. + * + * @param orig The original string. + * @param rep The substring to replace. + * @param with The replacement substring. + * + * @return A new string with the replacements. Should be freed by the caller. + */ +char *btkg_str_replace(const char *orig, const char *rep, const char *with); + +/** + * @brief Replaces placeholders in a string with specified values. + * + * @param input The input string containing placeholders. + * @param search The placeholder to search for. + * @param replace The string to replace the placeholder with. + * + * @return A new string with placeholders replaced. Should be freed by the caller. + */ char *btkg_str_replace_placeholder(char *input, const char *search, const char *replace); + +/** + * @brief Replaces escape sequences in a string with their corresponding characters. + * + * @param str The input string containing escape sequences. + */ void btkg_str_replace_escape_sequences(char *str); #endif /* STR_H */ diff --git a/src/target.c b/src/target.c index 88d7afb..54f8bde 100644 --- a/src/target.c +++ b/src/target.c @@ -1,5 +1,5 @@ /* -Copyright (c) 2014-2018 Jorge Matricali +Copyright (c) 2014-2024 Jorge Matricali Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal @@ -51,7 +51,11 @@ SOFTWARE. #define DEFAULT_PORT 22 /** - * Check if given port is valid + * @brief Check if a given port number is valid. + * + * @param port The port number to check. + * + * @return 1 if the port is valid (between 1 and 65535), otherwise 0. */ int btkg_target_port_is_valid(const long port) { @@ -59,7 +63,9 @@ int btkg_target_port_is_valid(const long port) } /** - * Initialize btkg_target_list_t + * @brief Initialize a btkg_target_list_t structure. + * + * @param target_list Pointer to the target list to initialize. */ void btkg_target_list_init(btkg_target_list_t *target_list) { @@ -68,7 +74,10 @@ void btkg_target_list_init(btkg_target_list_t *target_list) } /** - * Allocate new btkg_target_list_t + * @brief Allocate and initialize a new btkg_target_list_t structure. + * + * @return Pointer to the newly allocated btkg_target_list_t structure, + * or NULL if the allocation fails. */ btkg_target_list_t *btkg_target_list_create(void) { @@ -81,7 +90,9 @@ btkg_target_list_t *btkg_target_list_create(void) } /** - * Destroy and free btkg_target_list_t + * @brief Destroy and free a btkg_target_list_t structure. + * + * @param target_list Pointer to the target list to destroy. */ void btkg_target_list_destroy(btkg_target_list_t *target_list) { @@ -101,7 +112,14 @@ void btkg_target_list_destroy(btkg_target_list_t *target_list) } /** - * Parse target string into btkg_target_t structure + * @brief Parse a target string and create a btkg_target_t structure. + * + * @param line The target string (e.g., "192.168.1.1:8080"). + * + * @return Pointer to the newly created btkg_target_t structure, + * or NULL if the string is invalid. + * + * @note Exits the program with an error message if memory allocation fails. */ btkg_target_t *btkg_target_parse(char *line) { @@ -143,7 +161,10 @@ btkg_target_t *btkg_target_parse(char *line) } /** - * Append btkg_target_t into given btkg_target_list_t + * @brief Append a btkg_target_t structure to a btkg_target_list_t. + * + * @param target_list Pointer to the target list. + * @param target Pointer to the target to append. */ void btkg_target_list_append(btkg_target_list_t *target_list, btkg_target_t *target) @@ -163,7 +184,12 @@ void btkg_target_list_append(btkg_target_list_t *target_list, } /** - * Parse CIDR block and append as many btkg_target_t as needed into the given btkg_target_list_t + * @brief Parse a CIDR block and append all addresses in the range as + * btkg_target_t structures to the given btkg_target_list_t. + * + * @param target_list Pointer to the target list. + * @param range The CIDR block string (e.g., "192.168.1.0/24"). + * @param port The port number to use for all targets. */ void btkg_target_list_append_range(btkg_target_list_t *target_list, const char *range, uint16_t port) @@ -212,7 +238,11 @@ void btkg_target_list_append_range(btkg_target_list_t *target_list, } /** - * Load targets from a given file and append them into the given btkg_target_list_t + * @brief Load targets from a given file and append them into the + * given btkg_target_list_t. + * + * @param target_list Pointer to the target list. + * @param filename The path to the file containing target definitions. */ void btkg_target_list_load(btkg_target_list_t *target_list, const char *filename) diff --git a/src/target.h b/src/target.h index 8a9d68f..2cfd459 100644 --- a/src/target.h +++ b/src/target.h @@ -1,5 +1,5 @@ /* -Copyright (c) 2014-2018 Jorge Matricali +Copyright (c) 2014-2024 Jorge Matricali Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal @@ -25,33 +25,92 @@ SOFTWARE. #include +/** + * @brief Represents a network target with a hostname or IP address + * and a port number. + */ typedef struct { char *host; uint16_t port; } btkg_target_t; +/** + * @brief Represents a list of network targets. + */ typedef struct { size_t length; btkg_target_t *targets; } btkg_target_list_t; +/** + * @brief Check if a given port number is valid. + * + * @param port The port number to check. + * + * @return 1 if the port is valid (between 1 and 65535), otherwise 0. + */ int btkg_target_port_is_valid(const long port); +/** + * @brief Allocate and initialize a new btkg_target_list_t structure. + * + * @return Pointer to the newly allocated btkg_target_list_t structure, + * or NULL if the allocation fails. + */ btkg_target_list_t *btkg_target_list_create(void); +/** + * @brief Destroy and free a btkg_target_list_t structure. + * + * @param target_list Pointer to the target list to destroy. + */ void btkg_target_list_destroy(btkg_target_list_t *target_list); +/** + * @brief Initialize a btkg_target_list_t structure. + * + * @param target_list Pointer to the target list to initialize. + */ void btkg_target_list_init(btkg_target_list_t *target_list); +/** + * @brief Append a btkg_target_t structure to a btkg_target_list_t. + * + * @param target_list Pointer to the target list. + * @param target Pointer to the target to append. + */ void btkg_target_list_append(btkg_target_list_t *target_list, btkg_target_t *target); +/** + * @brief Parse a CIDR block and append all addresses in the range as + * btkg_target_t structures to the given btkg_target_list_t. + * + * @param target_list Pointer to the target list. + * @param range The CIDR block string (e.g., "192.168.1.0/24"). + * @param port The port number to use for all targets. + */ void btkg_target_list_append_range(btkg_target_list_t *target_list, const char *range, uint16_t port); +/** + * @brief Load targets from a given file and append them into the + * given btkg_target_list_t. + * + * @param target_list Pointer to the target list. + * @param filename The path to the file containing target definitions. + */ void btkg_target_list_load(btkg_target_list_t *target_list, const char *filename); +/** + * @brief Parse a target string and create a btkg_target_t structure. + * + * @param line The target string (e.g., "192.168.1.1:8080"). + * + * @return Pointer to the newly created btkg_target_t structure, + * or NULL if the string is invalid. + */ btkg_target_t *btkg_target_parse(char *line); -#endif /* TARGET_H */ +#endif // TARGET_H